daemora 1.0.1 → 1.0.3

package/src/tenants/TenantManager.js

@@ -4,7 +4,7 @@ import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from "node:
 import { config } from "../config/default.js";
 
 /**
- * TenantManager — per-user configuration and isolation for multi-tenant deployments.
+ * TenantManager - per-user configuration and isolation for multi-tenant deployments.
  *
  * A tenant is any unique user identified by their channel + userId:
  *   tenantId = "telegram:123456789"
@@ -12,22 +12,22 @@ import { config } from "../config/default.js";
  *   tenantId = "email:user@example.com"
  *
  * Each tenant can have:
- *   model          — override the default model (e.g. cheaper model for free tier)
- *   allowedPaths   — filesystem paths this tenant's tasks can access
- *   blockedPaths   — paths always blocked for this tenant
- *   maxCostPerTask — per-task spend limit (overrides global)
- *   maxDailyCost   — per-tenant daily budget
- *   tools          — tool allowlist (empty = all tools allowed by permission tier)
- *   mcpServers     — MCP server allowlist: ["github","linear"] | null (null = all allowed)
- *   modelRoutes    — task-type model overrides: { coder: "anthropic:...", researcher: "google:..." }
- *   encryptedApiKeys — AES-256-GCM encrypted per-tenant API keys (managed via setApiKey/deleteApiKey)
- *   suspended      — block all tasks from this tenant
- *   plan           — "free" | "pro" | "admin" (for display / future rate limiting)
- *   createdAt      — ISO timestamp of first message
- *   lastSeenAt     — ISO timestamp of last message
- *   totalCost      — lifetime spend for this tenant
- *   taskCount      — total tasks submitted
- *   notes          — free-text operator notes
+ *   model          - override the default model (e.g. cheaper model for free tier)
+ *   allowedPaths   - filesystem paths this tenant's tasks can access
+ *   blockedPaths   - paths always blocked for this tenant
+ *   maxCostPerTask - per-task spend limit (overrides global)
+ *   maxDailyCost   - per-tenant daily budget
+ *   tools          - tool allowlist (empty = all tools allowed by permission tier)
+ *   mcpServers     - MCP server allowlist: ["github","linear"] | null (null = all allowed)
+ *   modelRoutes    - task-type model overrides: { coder: "anthropic:...", researcher: "google:..." }
+ *   encryptedApiKeys - AES-256-GCM encrypted per-tenant API keys (managed via setApiKey/deleteApiKey)
+ *   suspended      - block all tasks from this tenant
+ *   plan           - "free" | "pro" | "admin" (for display / future rate limiting)
+ *   createdAt      - ISO timestamp of first message
+ *   lastSeenAt     - ISO timestamp of last message
+ *   totalCost      - lifetime spend for this tenant
+ *   taskCount      - total tasks submitted
+ *   notes          - free-text operator notes
  *
  * Storage: data/tenants/tenants.json (flat JSON map of tenantId → config)
  * Workspaces: data/tenants/{tenantId}/workspace/  (isolated per-tenant directory)
@@ -124,7 +124,7 @@ class TenantManager {
   }
 
   /**
-   * Update tenant config (partial update — only provided keys are changed).
+   * Update tenant config (partial update - only provided keys are changed).
    */
   set(tenantId, updates) {
     const tenants = this._load();
@@ -197,6 +197,61 @@ class TenantManager {
     return true;
   }
 
+  // ── Per-Tenant Channel Config ─────────────────────────────────────────────
+
+  /**
+   * Store a per-tenant channel credential, encrypted with AES-256-GCM.
+   * Valid keys: email, email_password, resend_api_key, resend_from
+   *
+   * @param {string} tenantId - e.g. "telegram:123"
+   * @param {string} key      - e.g. "email"
+   * @param {string} value    - plaintext credential value
+   */
+  setChannelConfig(tenantId, key, value) {
+    const tenants = this._load();
+    if (!tenants[tenantId]) tenants[tenantId] = _defaultTenant(tenantId);
+    tenants[tenantId].encryptedChannelConfig = tenants[tenantId].encryptedChannelConfig || {};
+    tenants[tenantId].encryptedChannelConfig[key] = _encryptTenantValue(value);
+    tenants[tenantId].updatedAt = new Date().toISOString();
+    this._save(tenants);
+    return true;
+  }
+
+  /**
+   * Delete a per-tenant channel credential.
+   */
+  deleteChannelConfig(tenantId, key) {
+    const tenants = this._load();
+    if (!tenants[tenantId]?.encryptedChannelConfig?.[key]) return false;
+    delete tenants[tenantId].encryptedChannelConfig[key];
+    tenants[tenantId].updatedAt = new Date().toISOString();
+    this._save(tenants);
+    return true;
+  }
+
+  /**
+   * List the credential keys stored for a tenant (not values).
+   */
+  listChannelConfigKeys(tenantId) {
+    const tenants = this._load();
+    return Object.keys(tenants[tenantId]?.encryptedChannelConfig || {});
+  }
+
+  /**
+   * Decrypt and return all channel credentials for a tenant.
+   * Returns {} if none stored.
+   */
+  getDecryptedChannelConfig(tenantId) {
+    const tenants = this._load();
+    const encrypted = tenants[tenantId]?.encryptedChannelConfig || {};
+    const result = {};
+    for (const [key, val] of Object.entries(encrypted)) {
+      const decrypted = _decryptTenantValue(val);
+      if (decrypted !== null) result[key] = decrypted;
+    }
+    return result;
+  }
+
   // ── Per-Tenant API Key Management ─────────────────────────────────────────
 
   /**
@@ -312,7 +367,8 @@ class TenantManager {
       sandbox: config.sandbox?.mode || "process",
       mcpServers: tenant?.mcpServers ?? null,          // null = all MCP servers allowed
       modelRoutes: tenant?.modelRoutes || null,         // null = use global env vars
-      apiKeys: tenant?.id ? this.getDecryptedApiKeys(tenant.id) : {},  // per-tenant API keys
+      apiKeys: tenant?.id ? this.getDecryptedApiKeys(tenant.id) : {},          // per-tenant AI provider keys
+      channelConfig: tenant?.id ? this.getDecryptedChannelConfig(tenant.id) : {},  // per-tenant channel credentials
     };
   }
 
@@ -360,9 +416,10 @@ function _defaultTenant(id) {
     maxCostPerTask: null,
     maxDailyCost: null,
     tools: null,
-    mcpServers: null,          // null = all MCP servers allowed; ["github","linear"] = allowlist
-    modelRoutes: null,         // null = use global env vars; { coder: "anthropic:..." }
-    encryptedApiKeys: {},      // AES-256-GCM encrypted per-tenant API keys
+    mcpServers: null,              // null = all MCP servers allowed; ["github","linear"] = allowlist
+    modelRoutes: null,             // null = use global env vars; { coder: "anthropic:..." }
+    encryptedApiKeys: {},          // AES-256-GCM encrypted per-tenant AI provider keys
+    encryptedChannelConfig: {},    // AES-256-GCM encrypted per-tenant channel credentials (email, resend, etc.)
     suspended: false,
     suspendReason: "",
     plan: "free",

package/src/tools/ToolRegistry.js

@@ -25,7 +25,7 @@ class ToolRegistry {
   }
 
   /**
-   * Get tool function map { name: fn } — backward compatible with current toolFunctions export.
+   * Get tool function map { name: fn } - backward compatible with current toolFunctions export.
    */
   getToolFunctions() {
     const fns = {};
@@ -36,7 +36,7 @@ class ToolRegistry {
   }
 
   /**
-   * Get tool description strings — backward compatible with current toolDescriptions export.
+   * Get tool description strings - backward compatible with current toolDescriptions export.
    */
   getToolDescriptions() {
     const descs = [];
@@ -50,7 +50,7 @@ class ToolRegistry {
   }
 
   /**
-   * Build tool docs for system prompt — grouped by category.
+   * Build tool docs for system prompt - grouped by category.
    */
   buildToolDocs() {
     const categories = {};

package/src/tools/applyPatch.js

@@ -1,5 +1,5 @@
 /**
- * applyPatch(filePath, patch) — Apply a unified diff patch to a file.
+ * applyPatch(filePath, patch) - Apply a unified diff patch to a file.
  * Handles multi-hunk edits that editFile's single find-replace can't do.
  * Inspired by OpenClaw's apply_patch tool.
  */
@@ -53,7 +53,7 @@ function applyHunk(fileLines, hunk, offset) {
     let ri = pos;
     for (const hunkLine of hunk.lines) {
       if (hunkLine.startsWith(" ") || hunkLine === "") {
-        // context line — must match
+        // context line - must match
         if (ri >= fileLines.length) return null;
         if (fileLines[ri].trimEnd() !== hunkLine.slice(1).trimEnd()) return null;
         ri++;

package/src/tools/browserAutomation.js

@@ -1,5 +1,5 @@
 /**
- * Browser Automation — Playwright-based web interaction.
+ * Browser Automation - Playwright-based web interaction.
  * Upgraded: multi-tab, navigation guard, dialog handling, waitFor, cookies.
  */
 
@@ -7,7 +7,7 @@ let browser = null;
 let browserContext = null;
 const pages = []; // Multi-tab support
 
-// Blocked navigation patterns — SSRF / security guard
+// Blocked navigation patterns - SSRF / security guard
 const NAV_BLOCKLIST = [
   /^file:\/\//i,
   /^(http:\/\/|https:\/\/)(127\.|0\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.|169\.254\.)/,
@@ -37,7 +37,7 @@ async function ensureBrowser() {
 
     // Auto-handle dialogs (accept by default)
     browserContext.on("dialog", async (dialog) => {
-      console.log(`      [browser] Auto-dismissed dialog: ${dialog.type()} — "${dialog.message().slice(0, 80)}"`);
+      console.log(`      [browser] Auto-dismissed dialog: ${dialog.type()} - "${dialog.message().slice(0, 80)}"`);
       await dialog.dismiss();
     });
 
@@ -148,7 +148,7 @@ export async function browserAction(action, param1, param2) {
             if (p.isClosed()) return `  ${i}: [closed]`;
             const title = await p.title().catch(() => "?");
             const url = p.url();
-            return `  ${i}${i === pages.length - 1 ? " (active)" : ""}: ${title} — ${url}`;
+            return `  ${i}${i === pages.length - 1 ? " (active)" : ""}: ${title} - ${url}`;
           })
         );
         return `Open tabs (${pages.length}):\n${titles.join("\n")}`;

package/src/tools/calendar.js

@@ -0,0 +1,155 @@
+/**
+ * calendar - Read and create calendar events.
+ * macOS: AppleScript (Calendar app). Google Calendar: Google Calendar API.
+ * Supports: list upcoming events, create event, delete event.
+ */
+import { execSync } from "node:child_process";
+
+export async function calendar(action, paramsJson) {
+  if (!action) return "Error: action required. Valid: list, create, delete, search";
+  const params = paramsJson
+    ? (typeof paramsJson === "string" ? JSON.parse(paramsJson) : paramsJson)
+    : {};
+
+  const { provider = "macos" } = params;
+
+  // ── macOS Calendar (AppleScript) ────────────────────────────────────────
+  if (provider === "macos") {
+    if (process.platform !== "darwin") {
+      return "Error: macOS Calendar provider only works on macOS";
+    }
+
+    if (action === "list") {
+      const days = params.days || 7;
+      const script = `
+        tell application "Calendar"
+          set startDate to current date
+          set endDate to (current date) + (${days} * days)
+          set eventList to ""
+          set theCalendars to every calendar
+          repeat with aCal in theCalendars
+            set theEvents to (every event of aCal whose start date >= startDate and start date <= endDate)
+            repeat with anEvent in theEvents
+              set eventList to eventList & summary of anEvent & " | " & (start date of anEvent as string) & "\\n"
+            end repeat
+          end repeat
+          return eventList
+        end tell
+      `;
+      try {
+        const out = execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, { encoding: "utf-8", timeout: 15000 });
+        if (!out.trim()) return `No events found in the next ${days} days`;
+        return `Upcoming events (next ${days} days):\n${out.trim()}`;
+      } catch (err) {
+        return `Calendar error: ${err.message}`;
+      }
+    }
+
+    if (action === "create") {
+      const { title, startDate, endDate, calendarName = "Calendar", notes = "" } = params;
+      if (!title) return "Error: title is required";
+      if (!startDate) return "Error: startDate is required (e.g. '2026-03-10T10:00:00')";
+
+      const start = new Date(startDate);
+      const end = endDate ? new Date(endDate) : new Date(start.getTime() + 60 * 60 * 1000);
+
+      const fmtDate = (d) => {
+        return `${d.getFullYear()}-${String(d.getMonth()+1).padStart(2,'0')}-${String(d.getDate()).padStart(2,'0')} ${String(d.getHours()).padStart(2,'0')}:${String(d.getMinutes()).padStart(2,'0')}:00`;
+      };
+
+      const script = `
+        tell application "Calendar"
+          tell calendar "${calendarName.replace(/"/g, '\\"')}"
+            make new event with properties {summary:"${title.replace(/"/g, '\\"')}", start date:date "${fmtDate(start)}", end date:date "${fmtDate(end)}"${notes ? `, description:"${notes.replace(/"/g, '\\"')}"` : ""}}
+          end tell
+        end tell
+      `;
+      try {
+        execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, { timeout: 10000 });
+        return `Event created: "${title}" on ${start.toLocaleString()}`;
+      } catch (err) {
+        return `Calendar create error: ${err.message}`;
+      }
+    }
+
+    if (action === "search") {
+      const { query } = params;
+      if (!query) return "Error: query is required";
+      const script = `
+        tell application "Calendar"
+          set hits to ""
+          repeat with aCal in every calendar
+            repeat with anEvent in (every event of aCal whose summary contains "${query.replace(/"/g, '\\"')}")
+              set hits to hits & summary of anEvent & " | " & (start date of anEvent as string) & "\\n"
+            end repeat
+          end repeat
+          return hits
+        end tell
+      `;
+      try {
+        const out = execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, { encoding: "utf-8", timeout: 15000 });
+        if (!out.trim()) return `No events found matching "${query}"`;
+        return `Events matching "${query}":\n${out.trim()}`;
+      } catch (err) {
+        return `Calendar search error: ${err.message}`;
+      }
+    }
+  }
+
+  // ── Google Calendar (API) ────────────────────────────────────────────────
+  if (provider === "google") {
+    const apiKey = process.env.GOOGLE_CALENDAR_API_KEY;
+    const calId = params.calendarId || process.env.GOOGLE_CALENDAR_ID || "primary";
+    if (!apiKey) return "Error: GOOGLE_CALENDAR_API_KEY env var required for Google Calendar provider";
+
+    const fetchFn = globalThis.fetch || (await import("node-fetch")).default;
+
+    if (action === "list") {
+      const timeMin = new Date().toISOString();
+      const maxResults = params.maxResults || 10;
+      const url = `https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calId)}/events?key=${apiKey}&timeMin=${timeMin}&maxResults=${maxResults}&singleEvents=true&orderBy=startTime`;
+      const res = await fetchFn(url);
+      const data = await res.json();
+      if (!res.ok) return `Google Calendar error: ${data.error?.message}`;
+      if (!data.items?.length) return "No upcoming events";
+      return data.items.map(e => `${e.summary} | ${e.start?.dateTime || e.start?.date}`).join("\n");
+    }
+
+    if (action === "create") {
+      const accessToken = process.env.GOOGLE_CALENDAR_ACCESS_TOKEN;
+      if (!accessToken) return "Error: GOOGLE_CALENDAR_ACCESS_TOKEN required to create Google Calendar events";
+      const { title, startDate, endDate, notes } = params;
+      if (!title || !startDate) return "Error: title and startDate required";
+      const event = {
+        summary: title,
+        description: notes || "",
+        start: { dateTime: new Date(startDate).toISOString() },
+        end: { dateTime: new Date(endDate || new Date(startDate).getTime() + 3600000).toISOString() },
+      };
+      const url = `https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calId)}/events`;
+      const res = await fetchFn(url, {
+        method: "POST",
+        headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify(event),
+      });
+      const data = await res.json();
+      if (!res.ok) return `Google Calendar create error: ${data.error?.message}`;
+      return `Event created: "${data.summary}" on ${data.start.dateTime}`;
+    }
+  }
+
+  return `Unknown action: "${action}" for provider "${provider}". Valid actions: list, create, search`;
+}
+
+export const calendarDescription =
+  `calendar(action: string, paramsJson?: object) - Read/create calendar events.
+  action: "list" | "create" | "search"
+  params.provider: "macos" (default, AppleScript) | "google" (Google Calendar API)
+  list params: { days?: 7, provider, calendarId? }
+  create params: { title, startDate: "ISO string", endDate?, calendarName?, notes?, provider }
+  search params: { query, provider }
+  Env vars: GOOGLE_CALENDAR_API_KEY, GOOGLE_CALENDAR_ID, GOOGLE_CALENDAR_ACCESS_TOKEN
+  Examples:
+    calendar("list", {"days":3})
+    calendar("create", {"title":"Team standup","startDate":"2026-03-10T09:00:00"})
+    calendar("list", {"provider":"google","maxResults":5})`;

package/src/tools/clipboard.js

@@ -0,0 +1,71 @@
+/**
+ * clipboard - Read from or write to the system clipboard.
+ * macOS: pbpaste/pbcopy. Linux: xclip/xsel. Windows: clip/powershell.
+ */
+import { execSync, execFileSync } from "node:child_process";
+
+function platform() {
+  return process.platform;
+}
+
+export async function clipboard(action, text) {
+  if (!action) return 'Error: action required. Valid: read, write, clear';
+
+  try {
+    if (action === "read") {
+      let out;
+      if (platform() === "darwin") {
+        out = execSync("pbpaste", { encoding: "utf-8", timeout: 5000 });
+      } else if (platform() === "linux") {
+        try {
+          out = execSync("xclip -selection clipboard -o", { encoding: "utf-8", timeout: 5000 });
+        } catch {
+          out = execSync("xsel --clipboard --output", { encoding: "utf-8", timeout: 5000 });
+        }
+      } else if (platform() === "win32") {
+        out = execSync("powershell -command Get-Clipboard", { encoding: "utf-8", timeout: 5000 });
+      } else {
+        return "Error: clipboard read not supported on this platform.";
+      }
+      const content = out.trim();
+      if (!content) return "(clipboard is empty)";
+      return `Clipboard content:\n${content}`;
+    }
+
+    if (action === "write") {
+      if (!text) return "Error: text is required for write.";
+      if (platform() === "darwin") {
+        execSync(`echo ${JSON.stringify(text)} | pbcopy`, { timeout: 5000 });
+      } else if (platform() === "linux") {
+        try {
+          execSync(`echo ${JSON.stringify(text)} | xclip -selection clipboard`, { timeout: 5000 });
+        } catch {
+          execSync(`echo ${JSON.stringify(text)} | xsel --clipboard --input`, { timeout: 5000 });
+        }
+      } else if (platform() === "win32") {
+        execSync(`echo ${text} | clip`, { timeout: 5000 });
+      } else {
+        return "Error: clipboard write not supported on this platform.";
+      }
+      const preview = text.length > 80 ? text.slice(0, 80) + "..." : text;
+      return `Copied to clipboard: "${preview}"`;
+    }
+
+    if (action === "clear") {
+      return await clipboard("write", "");
+    }
+
+    return `Unknown action: "${action}". Valid: read, write, clear`;
+  } catch (err) {
+    return `Clipboard error: ${err.message}. Make sure xclip or xsel is installed on Linux.`;
+  }
+}
+
+export const clipboardDescription =
+  `clipboard(action: string, text?: string) - Read or write the system clipboard.
+  action: "read" | "write" | "clear"
+  text: content to write (required for write)
+  Examples:
+    clipboard("read")                          → returns clipboard contents
+    clipboard("write", "Hello World")          → copies text to clipboard
+    clipboard("clear")                         → clears clipboard`;

package/src/tools/contacts.js

@@ -0,0 +1,138 @@
+/**
+ * contacts - Read and search contacts.
+ * macOS: AppleScript (Contacts app). Google: People API.
+ */
+import { execSync } from "node:child_process";
+
+export async function contacts(action, paramsJson) {
+  if (!action) return "Error: action required. Valid: search, list, get";
+  const params = paramsJson
+    ? (typeof paramsJson === "string" ? JSON.parse(paramsJson) : paramsJson)
+    : {};
+
+  const { provider = "macos" } = params;
+
+  // ── macOS Contacts (AppleScript) ────────────────────────────────────────
+  if (provider === "macos") {
+    if (process.platform !== "darwin") {
+      return "Error: macOS Contacts provider only works on macOS";
+    }
+
+    if (action === "search" || action === "list") {
+      const query = params.query || "";
+      const limit = params.limit || 20;
+
+      const searchFilter = query
+        ? `whose (first name contains "${query.replace(/"/g, '\\"')}" or last name contains "${query.replace(/"/g, '\\"')}" or (email addresses is not {} and value of item 1 of email addresses contains "${query.replace(/"/g, '\\"')}"))`
+        : "";
+
+      const script = `
+        tell application "Contacts"
+          set output to ""
+          set peopleList to every person ${searchFilter}
+          set resultCount to 0
+          repeat with aPerson in peopleList
+            if resultCount >= ${limit} then exit repeat
+            set personName to (first name of aPerson & " " & last name of aPerson)
+            set emails to ""
+            if (count of email addresses of aPerson) > 0 then
+              set emails to value of item 1 of email addresses of aPerson
+            end if
+            set phones to ""
+            if (count of phones of aPerson) > 0 then
+              set phones to value of item 1 of phones of aPerson
+            end if
+            set output to output & personName & " | " & emails & " | " & phones & "\\n"
+            set resultCount to resultCount + 1
+          end repeat
+          return output
+        end tell
+      `;
+
+      try {
+        const out = execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, { encoding: "utf-8", timeout: 15000 });
+        if (!out.trim()) return query ? `No contacts found matching "${query}"` : "No contacts found";
+        return `Contacts${query ? ` matching "${query}"` : ""}:\n${out.trim()}`;
+      } catch (err) {
+        return `Contacts error: ${err.message}. Make sure Contacts app access is granted.`;
+      }
+    }
+
+    if (action === "get") {
+      const { name } = params;
+      if (!name) return "Error: name is required";
+
+      const script = `
+        tell application "Contacts"
+          set aPerson to first person whose (first name & " " & last name) contains "${name.replace(/"/g, '\\"')}"
+          set output to "Name: " & first name of aPerson & " " & last name of aPerson & "\\n"
+          if (count of email addresses of aPerson) > 0 then
+            repeat with anEmail in email addresses of aPerson
+              set output to output & "Email (" & label of anEmail & "): " & value of anEmail & "\\n"
+            end repeat
+          end if
+          if (count of phones of aPerson) > 0 then
+            repeat with aPhone in phones of aPerson
+              set output to output & "Phone (" & label of aPhone & "): " & value of aPhone & "\\n"
+            end repeat
+          end if
+          if organization of aPerson is not missing value then
+            set output to output & "Company: " & organization of aPerson & "\\n"
+          end if
+          return output
+        end tell
+      `;
+
+      try {
+        const out = execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, { encoding: "utf-8", timeout: 10000 });
+        return out.trim() || `No contact found matching "${name}"`;
+      } catch (err) {
+        return `Contact lookup error: ${err.message}`;
+      }
+    }
+  }
+
+  // ── Google People API ────────────────────────────────────────────────────
+  if (provider === "google") {
+    const accessToken = process.env.GOOGLE_CONTACTS_ACCESS_TOKEN;
+    if (!accessToken) return "Error: GOOGLE_CONTACTS_ACCESS_TOKEN env var required";
+
+    const fetchFn = globalThis.fetch || (await import("node-fetch")).default;
+
+    if (action === "list" || action === "search") {
+      const query = params.query || "";
+      let url;
+      if (query) {
+        url = `https://people.googleapis.com/v1/people:searchContacts?query=${encodeURIComponent(query)}&readMask=names,emailAddresses,phoneNumbers`;
+      } else {
+        url = `https://people.googleapis.com/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=${params.limit || 20}`;
+      }
+      const res = await fetchFn(url, { headers: { "Authorization": `Bearer ${accessToken}` } });
+      const data = await res.json();
+      if (!res.ok) return `Google Contacts error: ${data.error?.message}`;
+      const people = data.connections || data.results?.map(r => r.person) || [];
+      if (!people.length) return "No contacts found";
+      return people.map(p => {
+        const name = p.names?.[0]?.displayName || "Unknown";
+        const email = p.emailAddresses?.[0]?.value || "";
+        const phone = p.phoneNumbers?.[0]?.value || "";
+        return `${name} | ${email} | ${phone}`;
+      }).join("\n");
+    }
+  }
+
+  return `Unknown action: "${action}" for provider "${provider}". Valid: search, list, get`;
+}
+
+export const contactsDescription =
+  `contacts(action: string, paramsJson?: object) - Search and read contacts.
+  action: "search" | "list" | "get"
+  params.provider: "macos" (default, Contacts app) | "google" (People API)
+  search/list params: { query?, limit?: 20 }
+  get params: { name }
+  Env vars: GOOGLE_CONTACTS_ACCESS_TOKEN
+  Examples:
+    contacts("search", {"query":"John"})
+    contacts("list", {"limit":10})
+    contacts("get", {"name":"Alice Smith"})
+    contacts("search", {"provider":"google","query":"alice"})`;

package/src/tools/createDocument.js

@@ -2,7 +2,7 @@ import { writeFileSync, mkdirSync, readFileSync } from "fs";
 import { dirname } from "path";
 
 /**
- * Create Document — creates Markdown, text, PDF, or DOCX documents.
+ * Create Document - creates Markdown, text, PDF, or DOCX documents.
  * Upgraded: better PDF rendering (bold, italic, code, tables, numbered lists),
  *           optional DOCX support via 'docx' package.
  */
@@ -26,7 +26,7 @@ export async function createDocument(filePath, content, format) {
       return await createDOCX(filePath, content);
     }
 
-    // Markdown / text / html — write as-is
+    // Markdown / text / html - write as-is
     writeFileSync(filePath, content, "utf-8");
     console.log(`      [createDocument] Written: ${filePath} (${content.length} chars)`);
     return `Document created: ${filePath} (${content.length} characters)`;