daemora 1.0.0

package/src/tools/sendEmail.js

@@ -0,0 +1,118 @@
+/**
+ * Send Email — sends email via SMTP (nodemailer).
+ * Upgraded: CC/BCC, attachments, replyTo, email validation, optionsJson support.
+ */
+
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function validateEmail(addr) {
+  return EMAIL_REGEX.test(addr.trim());
+}
+
+function parseAddressList(val) {
+  if (!val) return null;
+  return val.split(",").map((a) => a.trim()).filter(Boolean);
+}
+
+let transporter = null;
+
+async function getTransporter() {
+  if (transporter) return transporter;
+
+  const user = process.env.EMAIL_USER;
+  const pass = process.env.EMAIL_PASSWORD;
+  const host = process.env.EMAIL_SMTP_HOST || "smtp.gmail.com";
+  const port = parseInt(process.env.EMAIL_SMTP_PORT || "587", 10);
+
+  if (!user || !pass) {
+    return null;
+  }
+
+  const nodemailer = await import("nodemailer");
+  transporter = nodemailer.default.createTransport({
+    host,
+    port,
+    secure: port === 465,
+    auth: { user, pass },
+  });
+
+  return transporter;
+}
+
+export async function sendEmail(to, subject, body, optionsJson) {
+  if (!to || !subject || !body) {
+    return "Error: to, subject, and body are all required.";
+  }
+
+  // Parse options
+  let opts = {};
+  if (optionsJson) {
+    try { opts = JSON.parse(optionsJson); } catch {}
+  }
+
+  const cc = opts.cc ? parseAddressList(opts.cc) : null;
+  const bcc = opts.bcc ? parseAddressList(opts.bcc) : null;
+  const replyTo = opts.replyTo || null;
+  const attachments = Array.isArray(opts.attachments) ? opts.attachments : null; // [{filename, path}]
+
+  // Validate addresses
+  const toList = parseAddressList(to);
+  if (!toList || toList.length === 0) return "Error: 'to' must have at least one valid address.";
+  for (const addr of toList) {
+    if (!validateEmail(addr)) return `Error: Invalid email address: "${addr}"`;
+  }
+  if (cc) {
+    for (const addr of cc) {
+      if (!validateEmail(addr)) return `Error: Invalid CC address: "${addr}"`;
+    }
+  }
+  if (bcc) {
+    for (const addr of bcc) {
+      if (!validateEmail(addr)) return `Error: Invalid BCC address: "${addr}"`;
+    }
+  }
+
+  console.log(`      [sendEmail] To: ${to} | Subject: "${subject}"${cc ? ` | CC: ${cc.join(",")}` : ""}${bcc ? ` | BCC: ${bcc.join(",")}` : ""}`);
+
+  const smtp = await getTransporter();
+  if (!smtp) {
+    return "Error: Email not configured. Set EMAIL_USER and EMAIL_PASSWORD in .env";
+  }
+
+  try {
+    const mailOptions = {
+      from: process.env.EMAIL_USER,
+      to: toList.join(", "),
+      subject,
+      text: body,
+      html: body.includes("<") ? body : undefined,
+    };
+
+    if (cc) mailOptions.cc = cc.join(", ");
+    if (bcc) mailOptions.bcc = bcc.join(", ");
+    if (replyTo) mailOptions.replyTo = replyTo;
+    if (attachments) {
+      mailOptions.attachments = attachments.map((a) => ({
+        filename: a.filename,
+        path: a.path,
+      }));
+    }
+
+    const info = await smtp.sendMail(mailOptions);
+
+    console.log(`      [sendEmail] Sent: ${info.messageId}`);
+
+    const extra = [];
+    if (cc) extra.push(`CC: ${cc.join(", ")}`);
+    if (bcc) extra.push(`BCC: ${bcc.join(", ")}`);
+    if (attachments) extra.push(`${attachments.length} attachment(s)`);
+
+    return `Email sent to ${to}${extra.length ? ` (${extra.join(", ")})` : ""}. Message ID: ${info.messageId}`;
+  } catch (error) {
+    console.log(`      [sendEmail] Failed: ${error.message}`);
+    return `Failed to send email: ${error.message}`;
+  }
+}
+
+export const sendEmailDescription =
+  'sendEmail(to: string, subject: string, body: string, optionsJson?: string) - Send email via SMTP. optionsJson: {"cc":"a@b.com,c@d.com","bcc":"e@f.com","replyTo":"r@s.com","attachments":[{"filename":"report.pdf","path":"/tmp/report.pdf"}]}. Requires EMAIL_USER + EMAIL_PASSWORD in .env.';

package/src/tools/sendFile.js

@@ -0,0 +1,63 @@
+/**
+ * sendFile(channel, target, filePath, caption?) — Send a file/image/video to a user on any channel.
+ *
+ * The agent uses this to proactively deliver:
+ * - Screenshots it captured (screenCapture → sendFile)
+ * - Images it generated or processed
+ * - Videos it recorded
+ * - Documents/PDFs it created (createDocument → sendFile)
+ * - Any other file the user should receive
+ *
+ * channel: "telegram" | "discord" | "slack" | "whatsapp" | "email"
+ * target:  chat ID, user ID, channel ID, phone number, or email — depends on channel
+ * filePath: absolute path to the local file to send
+ * caption: optional text caption alongside the file
+ */
+import channelRegistry from "../channels/index.js";
+import { existsSync, statSync } from "node:fs";
+
+const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB — most platforms limit around this
+
+export async function sendFile(channel, target, filePath, caption) {
+  try {
+    if (!channel) return "Error: channel is required";
+    if (!target)  return "Error: target is required (chat ID, user ID, phone, or email)";
+    if (!filePath) return "Error: filePath is required";
+
+    if (!existsSync(filePath)) {
+      return `Error: File not found: ${filePath}`;
+    }
+
+    const size = statSync(filePath).size;
+    if (size > MAX_FILE_SIZE) {
+      return `Error: File too large (${(size / 1024 / 1024).toFixed(1)} MB). Maximum is 50 MB.`;
+    }
+
+    const ch = channelRegistry.get(channel.toLowerCase());
+    if (!ch) {
+      const available = channelRegistry.list().map((c) => c.name).join(", ");
+      return `Error: Channel "${channel}" not found. Available: ${available || "none"}`;
+    }
+
+    if (!ch.running) {
+      return `Error: Channel "${channel}" is not running.`;
+    }
+
+    if (typeof ch.sendFile !== "function") {
+      return `Error: Channel "${channel}" does not support file sending yet.`;
+    }
+
+    await ch.sendFile({ chatId: target, userId: target, channelId: target }, filePath, caption || "");
+
+    return `File sent via ${channel} to ${target}: ${filePath}`;
+  } catch (error) {
+    return `Error sending file: ${error.message}`;
+  }
+}
+
+export const sendFileDescription =
+  'sendFile(channel, target, filePath, caption?) — Send a file, image, or video to a user. ' +
+  'channel: "telegram"|"discord"|"slack"|"email". ' +
+  'target: chat ID (Telegram), user/channel ID (Discord/Slack), or email. ' +
+  'filePath: absolute path to the file. caption: optional text alongside the file. ' +
+  'Use after screenCapture, createDocument, or imageAnalysis to deliver results to the user.';

package/src/tools/textToSpeech.js

@@ -0,0 +1,161 @@
+/**
+ * textToSpeech(text, optionsJson?) — Convert text to speech and save as audio file.
+ *
+ * Primary:  OpenAI TTS (tts-1-hd) — uses the same OPENAI_API_KEY already configured.
+ * Optional: ElevenLabs via ELEVENLABS_API_KEY (higher quality, more voices).
+ *
+ * Unlike OpenClaw's /voice command (config-only, iOS-only), this is a proper
+ * agent-callable tool. Chain with sendFile() to deliver audio to the user.
+ *
+ * OpenAI voices:    alloy, echo, fable, onyx, nova (default), shimmer
+ * ElevenLabs:       any voice from your ElevenLabs account, set via voiceId option
+ *
+ * Auto-splits text > 4096 chars (OpenAI hard limit) into sequential MP3 files.
+ */
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const TMP_DIR = join(tmpdir(), "daemora-tts");
+const OPENAI_CHAR_LIMIT = 4096;
+const ELEVENLABS_CHAR_LIMIT = 5000;
+
+export async function textToSpeech(text, optionsJson) {
+  try {
+    if (!text || text.trim().length === 0) {
+      return "Error: text is required";
+    }
+
+    const opts = optionsJson ? JSON.parse(optionsJson) : {};
+    const provider = opts.provider?.toLowerCase() || "openai";
+
+    // Prefer ElevenLabs if key is present and provider not forced
+    if (provider === "elevenlabs" || (provider === "auto" && process.env.ELEVENLABS_API_KEY)) {
+      return await _elevenLabs(text.trim(), opts);
+    }
+
+    return await _openAI(text.trim(), opts);
+  } catch (err) {
+    return `Error in textToSpeech: ${err.message}`;
+  }
+}
+
+// ── OpenAI TTS ────────────────────────────────────────────────────────────────
+
+async function _openAI(text, opts) {
+  if (!process.env.OPENAI_API_KEY) {
+    return "Error: textToSpeech requires OPENAI_API_KEY";
+  }
+
+  const { default: OpenAI } = await import("openai");
+  const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+  const voice  = opts.voice  || "nova";    // nova = clear, neutral, works great for most use cases
+  const speed  = Math.max(0.25, Math.min(4.0, parseFloat(opts.speed  || "1.0")));
+  const format = opts.format || "mp3";     // mp3 | opus | aac | flac
+  const model  = opts.hd === false ? "tts-1" : "tts-1-hd"; // tts-1-hd = better quality
+
+  mkdirSync(TMP_DIR, { recursive: true });
+
+  // Split into chunks if text exceeds API limit
+  const chunks = _splitText(text, OPENAI_CHAR_LIMIT);
+
+  if (chunks.length === 1) {
+    const response = await client.audio.speech.create({ model, voice, input: chunks[0], speed, response_format: format });
+    const filePath = join(TMP_DIR, `speech-${Date.now()}.${format}`);
+    writeFileSync(filePath, Buffer.from(await response.arrayBuffer()));
+    return `Audio saved to: ${filePath}`;
+  }
+
+  // Multiple chunks — save each sequentially, return all paths
+  const paths = [];
+  for (let i = 0; i < chunks.length; i++) {
+    const response = await client.audio.speech.create({ model, voice, input: chunks[i], speed, response_format: format });
+    const filePath = join(TMP_DIR, `speech-${Date.now()}-part${i + 1}.${format}`);
+    writeFileSync(filePath, Buffer.from(await response.arrayBuffer()));
+    paths.push(filePath);
+  }
+
+  return `Text was split into ${paths.length} audio files:\n${paths.join("\n")}\nUse sendFile() to deliver each one.`;
+}
+
+// ── ElevenLabs TTS ────────────────────────────────────────────────────────────
+
+async function _elevenLabs(text, opts) {
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+  if (!apiKey) {
+    return "Error: provider=elevenlabs requires ELEVENLABS_API_KEY";
+  }
+
+  // Default: Rachel — professional female voice, works well for most content
+  const voiceId  = opts.voiceId  || "21m00Tcm4TlvDq8ikWAM";
+  const modelId  = opts.modelId  || "eleven_multilingual_v2"; // supports 29 languages
+  const stability       = parseFloat(opts.stability       || "0.5");
+  const similarityBoost = parseFloat(opts.similarityBoost || "0.75");
+
+  const chunk = text.slice(0, ELEVENLABS_CHAR_LIMIT);
+  if (text.length > ELEVENLABS_CHAR_LIMIT) {
+    console.log(`[textToSpeech] ElevenLabs: text truncated to ${ELEVENLABS_CHAR_LIMIT} chars`);
+  }
+
+  const res = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`, {
+    method: "POST",
+    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      text: chunk,
+      model_id: modelId,
+      voice_settings: { stability, similarity_boost: similarityBoost },
+    }),
+    signal: AbortSignal.timeout(60000),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    return `Error: ElevenLabs API returned HTTP ${res.status}${body ? `: ${body.slice(0, 200)}` : ""}`;
+  }
+
+  mkdirSync(TMP_DIR, { recursive: true });
+  const filePath = join(TMP_DIR, `speech-eleven-${Date.now()}.mp3`);
+  writeFileSync(filePath, Buffer.from(await res.arrayBuffer()));
+  return `Audio saved to: ${filePath}`;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Split text at sentence boundaries to keep chunks under maxLength.
+ * Sentence-aware: tries to break at ". ", "? ", "! " before hard-cutting.
+ */
+function _splitText(text, maxLength) {
+  if (text.length <= maxLength) return [text];
+
+  const chunks = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+
+    // Try to break at sentence boundary near the limit
+    let idx = -1;
+    for (const sep of [". ", "? ", "! ", "\n\n", "\n", " "]) {
+      const pos = remaining.lastIndexOf(sep, maxLength);
+      if (pos > maxLength * 0.5) { idx = pos + sep.length; break; }
+    }
+    if (idx === -1) idx = maxLength;
+
+    chunks.push(remaining.slice(0, idx).trim());
+    remaining = remaining.slice(idx).trimStart();
+  }
+
+  return chunks.filter(Boolean);
+}
+
+export const textToSpeechDescription =
+  'textToSpeech(text: string, optionsJson?: string) — Convert text to an audio file using OpenAI TTS (default) or ElevenLabs. ' +
+  'optionsJson: {"voice":"nova|alloy|echo|fable|onyx|shimmer","speed":1.0,"format":"mp3","hd":true,"provider":"openai|elevenlabs","voiceId":"<elevenlabs-id>"}. ' +
+  'Requires OPENAI_API_KEY (or ELEVENLABS_API_KEY for ElevenLabs). ' +
+  'Auto-splits long texts. Returns the saved file path. Chain with sendFile() to deliver audio to the user.';

package/src/tools/transcribeAudio.js

@@ -0,0 +1,82 @@
+/**
+ * transcribeAudio(audioPath, prompt?) — Transcribe audio/voice files to text using OpenAI Whisper.
+ *
+ * Supports: local file paths and HTTPS URLs.
+ * Formats: mp3, mp4, mpeg, mpga, m4a, wav, webm, ogg, oga, flac
+ *
+ * Used by channels to convert voice messages to text before processing as tasks.
+ * Can also be called directly by the agent to transcribe any audio file.
+ */
+import { createReadStream, writeFileSync, existsSync } from "node:fs";
+import { join, extname, basename } from "node:path";
+import { tmpdir } from "node:os";
+import OpenAI from "openai";
+
+const SUPPORTED_EXTENSIONS = new Set([
+  ".mp3", ".mp4", ".mpeg", ".mpga", ".m4a", ".wav", ".webm", ".ogg", ".oga", ".flac"
+]);
+
+// Telegram voices come as .oga (ogg audio) — map to .ogg for Whisper compatibility
+const EXT_REMAP = { ".oga": ".ogg" };
+
+export async function transcribeAudio(audioPath, prompt) {
+  try {
+    if (!audioPath) return "Error: audioPath is required";
+
+    if (!process.env.OPENAI_API_KEY) {
+      return "Error: transcribeAudio requires OPENAI_API_KEY (uses OpenAI Whisper API)";
+    }
+
+    let localPath = audioPath;
+
+    // Download if URL
+    if (audioPath.startsWith("https://") || audioPath.startsWith("http://")) {
+      const ext = extname(new URL(audioPath).pathname) || ".ogg";
+      const tmpPath = join(tmpdir(), `audio-${Date.now()}${ext}`);
+
+      const res = await fetch(audioPath, { signal: AbortSignal.timeout(30000) });
+      if (!res.ok) return `Error downloading audio: HTTP ${res.status}`;
+
+      const buffer = await res.arrayBuffer();
+      writeFileSync(tmpPath, Buffer.from(buffer));
+      localPath = tmpPath;
+    }
+
+    if (!existsSync(localPath)) {
+      return `Error: Audio file not found: ${localPath}`;
+    }
+
+    let ext = extname(localPath).toLowerCase();
+    // Remap extensions Whisper doesn't recognise
+    if (EXT_REMAP[ext]) {
+      ext = EXT_REMAP[ext];
+    }
+
+    if (!SUPPORTED_EXTENSIONS.has(ext)) {
+      return `Error: Unsupported audio format: ${ext}. Supported: ${[...SUPPORTED_EXTENSIONS].join(", ")}`;
+    }
+
+    const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+    const transcription = await openai.audio.transcriptions.create({
+      file: createReadStream(localPath),
+      model: "whisper-1",
+      prompt: prompt || undefined,   // optional context hint
+      response_format: "text",
+    });
+
+    // transcription is a string when response_format is "text"
+    const text = typeof transcription === "string"
+      ? transcription.trim()
+      : (transcription.text || "").trim();
+
+    if (!text) return "Transcription returned empty — audio may be silent or too short.";
+    return text;
+
+  } catch (error) {
+    return `Error transcribing audio: ${error.message}`;
+  }
+}
+
+export const transcribeAudioDescription =
+  'transcribeAudio(audioPath: string, prompt?: string) — Transcribe a voice/audio file to text using OpenAI Whisper. audioPath: local file path or HTTPS URL. Formats: mp3, mp4, m4a, wav, webm, ogg, flac. Requires OPENAI_API_KEY.';

package/src/tools/useMCP.js

@@ -0,0 +1,29 @@
+import { runMCPAgent } from "../mcp/MCPAgentRunner.js";
+import tenantContext from "../tenants/TenantContext.js";
+
+/**
+ * useMCP — delegate a task to a specialist agent for a specific MCP server.
+ *
+ * The specialist agent receives ONLY that server's tools and a focused system prompt.
+ * This keeps context lean: main agent stays uncluttered, specialist stays focused.
+ *
+ * @param {string} serverName       - MCP server name (e.g. "github", "notion", "slack")
+ * @param {string} taskDescription  - Full task spec — the agent has no other context
+ * @returns {Promise<string>}       - Specialist agent's final response
+ */
+export async function useMCP(serverName, taskDescription) {
+  // Enforce per-tenant MCP server allowlist
+  const store = tenantContext.getStore();
+  const allowedMcpServers = store?.resolvedConfig?.mcpServers ?? null;
+  if (allowedMcpServers !== null && !allowedMcpServers.includes(serverName)) {
+    return `Access denied: MCP server "${serverName}" is not in your allowed list. Contact the operator.`;
+  }
+
+  return runMCPAgent(serverName, taskDescription);
+}
+
+export const useMCPDescription =
+  `useMCP(serverName: string, taskDescription: string) - Delegate a task to a specialist MCP agent for the named server.
+  - serverName: the MCP server to use (use manageMCP("list") to see available servers)
+  - taskDescription: comprehensive task spec — the specialist has no other context, so include all details
+  - The specialist gets ONLY that server's tools — lean context, no confusion with built-in tools`;

package/src/tools/webFetch.js

@@ -0,0 +1,150 @@
+/**
+ * webFetch(url, optionsJson?) — Fetch URL content with proper HTML conversion, caching, and SSRF protection.
+ * Upgraded: html-to-text library, 15-min cache, SSRF guard, 50K char limit, GitHub URL conversion.
+ */
+import { convert } from "html-to-text";
+import { URL } from "node:url";
+
+// Private IP ranges — SSRF protection
+const PRIVATE_RANGES = [
+  /^127\./,
+  /^10\./,
+  /^172\.(1[6-9]|2[0-9]|3[01])\./,
+  /^192\.168\./,
+  /^169\.254\./,
+  /^0\./,
+  /^::1$/,
+  /^fc00:/i,
+  /^fe80:/i,
+  /^localhost$/i,
+];
+
+// Response cache: url → { content, expiresAt }
+const cache = new Map();
+const CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+const MAX_CACHE_SIZE = 100;
+
+function isPrivateIP(hostname) {
+  return PRIVATE_RANGES.some((r) => r.test(hostname));
+}
+
+function convertGitHubUrl(url) {
+  // Convert GitHub blob URLs to raw content URLs
+  const match = url.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/(.+)$/);
+  if (match) {
+    return `https://raw.githubusercontent.com/${match[1]}/${match[2]}/${match[3]}`;
+  }
+  return url;
+}
+
+function checkCache(url) {
+  const entry = cache.get(url);
+  if (entry && Date.now() < entry.expiresAt) {
+    return entry.content;
+  }
+  if (entry) cache.delete(url); // expired
+  return null;
+}
+
+function setCache(url, content) {
+  if (cache.size >= MAX_CACHE_SIZE) {
+    // Evict oldest entry
+    const firstKey = cache.keys().next().value;
+    cache.delete(firstKey);
+  }
+  cache.set(url, { content, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+export async function webFetch(url, optionsJson) {
+  const opts = optionsJson ? JSON.parse(optionsJson) : {};
+  const maxChars = opts.maxChars ? parseInt(opts.maxChars) : 50000;
+
+  console.log(`      [webFetch] Fetching: ${url}`);
+
+  try {
+    // Validate URL
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return `Error: Invalid URL: ${url}`;
+    }
+
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+      return `Error: Only http and https URLs are supported (got ${parsed.protocol})`;
+    }
+
+    // SSRF protection
+    if (isPrivateIP(parsed.hostname)) {
+      return `Error: Access to private/internal addresses is not allowed: ${parsed.hostname}`;
+    }
+
+    // GitHub blob → raw URL
+    url = convertGitHubUrl(url);
+
+    // Check cache
+    const cached = checkCache(url);
+    if (cached) {
+      console.log(`      [webFetch] Cache hit for ${url}`);
+      return cached;
+    }
+
+    const startTime = Date.now();
+    const response = await fetch(url, {
+      headers: {
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.5",
+      },
+      signal: AbortSignal.timeout(15000),
+      redirect: "follow",
+    });
+    const elapsed = Date.now() - startTime;
+
+    if (!response.ok) {
+      return `HTTP Error ${response.status}: ${response.statusText}`;
+    }
+
+    const contentType = response.headers.get("content-type") || "";
+    console.log(`      [webFetch] ${response.status} | ${contentType} | ${elapsed}ms`);
+
+    let result;
+
+    if (contentType.includes("application/json")) {
+      const json = await response.json();
+      result = JSON.stringify(json, null, 2).slice(0, maxChars);
+    } else if (contentType.includes("text/html")) {
+      const html = await response.text();
+      // Use html-to-text for proper conversion
+      result = convert(html, {
+        wordwrap: 120,
+        selectors: [
+          { selector: "a", options: { ignoreHref: false } },
+          { selector: "img", format: "skip" },
+          { selector: "script", format: "skip" },
+          { selector: "style", format: "skip" },
+          { selector: "nav", format: "skip" },
+          { selector: "footer", format: "skip" },
+          { selector: "header", options: { uppercase: false } },
+        ],
+      });
+      result = result.replace(/\n{3,}/g, "\n\n").trim().slice(0, maxChars);
+    } else {
+      result = (await response.text()).slice(0, maxChars);
+    }
+
+    if (result.length === maxChars) {
+      result += `\n\n[Content truncated at ${maxChars} chars. Use optionsJson '{"maxChars":100000}' for more.]`;
+    }
+
+    console.log(`      [webFetch] Got ${result.length} chars`);
+    setCache(url, result);
+    return result;
+  } catch (error) {
+    console.log(`      [webFetch] Failed: ${error.message}`);
+    return `Error fetching URL: ${error.message}`;
+  }
+}
+
+export const webFetchDescription =
+  'webFetch(url: string, optionsJson?: string) - Fetch content from a URL. HTML is properly converted to readable text. optionsJson: {"maxChars":50000}. Responses are cached for 15 minutes. Private/internal URLs are blocked for security.';