daemora 1.0.1 → 1.0.3

package/src/tools/manageMCP.js

@@ -1,17 +1,35 @@
 import mcpManager from "../mcp/MCPManager.js";
 
 /**
- * manageMCP — inspect, add, remove, and reload MCP server connections at runtime.
+ * Strip credentials from an MCP server config object before it can reach agent output.
+ * env contains API keys (GITHUB_TOKEN etc.), headers contains Bearer tokens.
+ * We replace values with "[REDACTED]" rather than deleting keys so the agent can see
+ * which credential fields are configured without seeing the actual values.
+ */
+function _stripCredentials(serverConfig) {
+  if (!serverConfig || typeof serverConfig !== "object") return serverConfig;
+  const safe = { ...serverConfig };
+  if (safe.env && typeof safe.env === "object") {
+    safe.env = Object.fromEntries(Object.keys(safe.env).map(k => [k, "[REDACTED]"]));
+  }
+  if (safe.headers && typeof safe.headers === "object") {
+    safe.headers = Object.fromEntries(Object.keys(safe.headers).map(k => [k, "[REDACTED]"]));
+  }
+  return safe;
+}
+
+/**
+ * manageMCP - inspect, add, remove, and reload MCP server connections at runtime.
  *
  * Actions:
- *   list    — all configured servers and their tool names
- *   tools   — full tool list with descriptions for a specific server
- *   status  — connection status summary (same as list)
- *   add     — add a new MCP server (saved to config/mcp.json + connected immediately)
- *   remove  — disconnect and remove a server from config
- *   enable  — enable a disabled server (reconnects it)
- *   disable — disable a server (disconnects it, keeps in config)
- *   reload  — reconnect a server (useful after config changes)
+ *   list    - all configured servers and their tool names
+ *   tools   - full tool list with descriptions for a specific server
+ *   status  - connection status summary (same as list)
+ *   add     - add a new MCP server (saved to config/mcp.json + connected immediately)
+ *   remove  - disconnect and remove a server from config
+ *   enable  - enable a disabled server (reconnects it)
+ *   disable - disable a server (disconnects it, keeps in config)
+ *   reload  - reconnect a server (useful after config changes)
  */
 export async function manageMCP(action, paramsJson) {
   const params = paramsJson
@@ -33,13 +51,13 @@ export async function manageMCP(action, paramsJson) {
 
       const lines = [];
       for (const name of configuredNames) {
-        const cfg = allConfig[name];
+        const cfg = _stripCredentials(allConfig[name]);
         const live = connected.find(s => s.name === name);
         if (cfg.enabled === false) {
           lines.push(`⏸️  disabled  ${name}`);
         } else if (live?.connected) {
           const toolList = live.tools.length > 0 ? live.tools.join(", ") : "(no tools)";
-          lines.push(`✅ connected ${name}: ${live.tools.length} tools — ${toolList}`);
+          lines.push(`✅ connected ${name}: ${live.tools.length} tools - ${toolList}`);
         } else {
           lines.push(`❌ disconnected ${name}`);
         }
@@ -77,12 +95,12 @@ export async function manageMCP(action, paramsJson) {
 
       const serverConfig = {};
       if (command) {
-        // stdio — credentials go as env vars injected into the subprocess
+        // stdio - credentials go as env vars injected into the subprocess
         serverConfig.command = command;
         if (args) serverConfig.args = args;
         if (env) serverConfig.env = env;   // { "GITHUB_TOKEN": "ghp_..." }
       } else {
-        // http/sse — credentials go as HTTP request headers
+        // http/sse - credentials go as HTTP request headers
         serverConfig.url = url;
         if (transport) serverConfig.transport = transport;  // "sse" or omit for HTTP
         if (headers) serverConfig.headers = headers;        // { "Authorization": "Bearer ${TOKEN}" }
@@ -143,8 +161,8 @@ export async function manageMCP(action, paramsJson) {
 export const manageMCPDescription =
   `manageMCP(action: string, paramsJson?: string) - Manage MCP server connections at runtime. Changes saved to config/mcp.json.
   Actions:
-    list/status  - no params — all servers with connection status and tool names
-    tools        - {"server":"github"} — full tool list for a server, or {} for all servers
+    list/status  - no params - all servers with connection status and tool names
+    tools        - {"server":"github"} - full tool list for a server, or {} for all servers
     add          - Add and immediately connect a server:
                    stdio (auth via env vars passed to subprocess):
                      {"name":"github","command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"ghp_..."}}
@@ -152,8 +170,8 @@ export const manageMCPDescription =
                      {"name":"myapi","url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer \${MY_TOKEN}"}}
                    SSE (auth via request headers, applied to both GET stream and POST calls):
                      {"name":"myapi","url":"https://api.example.com/sse","transport":"sse","headers":{"Authorization":"Bearer \${MY_TOKEN}","X-API-Key":"\${MY_KEY}"}}
-                   Header values support \${VAR_NAME} — expanded from process.env at connect time.
-    remove       - {"name":"github"} — disconnect and remove from config
-    enable       - {"name":"github"} — re-enable a disabled server (reconnects)
-    disable      - {"name":"github"} — disconnect and mark disabled in config
-    reload       - {"name":"github"} — reconnect (useful after editing config)`;
+                   Header values support \${VAR_NAME} - expanded from process.env at connect time.
+    remove       - {"name":"github"} - disconnect and remove from config
+    enable       - {"name":"github"} - re-enable a disabled server (reconnects)
+    disable      - {"name":"github"} - disconnect and mark disabled in config
+    reload       - {"name":"github"} - reconnect (useful after editing config)`;

package/src/tools/memory.js

@@ -3,11 +3,12 @@ import { join } from "path";
 import { randomUUID } from "node:crypto";
 import { config } from "../config/default.js";
 import tenantContext from "../tenants/TenantContext.js";
+import { generateEmbedding, getEmbeddingProvider } from "../utils/Embeddings.js";
 
 /**
- * Memory tools — read/write/search/prune persistent agent memory.
+ * Memory tools - read/write/search/prune persistent agent memory.
  * Upgraded: category tags, context lines in search, pruning old entries.
- * Phase 17: Per-tenant isolation — each tenant gets their own memory dir.
+ * Phase 17: Per-tenant isolation - each tenant gets their own memory dir.
  *
  * - MEMORY.md: Long-term facts (timestamped entries with optional category)
  * - data/memory/YYYY-MM-DD.md: Daily logs
@@ -22,7 +23,7 @@ const _GLOBAL_EMBEDDINGS_PATH = join(config.memoryDir, "embeddings.json");
 
 /**
  * Get memory paths for the current tenant context (or global paths if no tenant).
- * Called at runtime from each function — NOT at module load — so AsyncLocalStorage is active.
+ * Called at runtime from each function - NOT at module load - so AsyncLocalStorage is active.
  */
 function _getMemoryPaths() {
   const store = tenantContext.getStore();
@@ -55,11 +56,11 @@ function _getPathsForTenantId(tenantId) {
 
 // ─── Vector / Semantic Memory ─────────────────────────────────────────────────
 // Stored separately from MEMORY.md so the markdown file stays human-readable.
-// Uses OpenAI text-embedding-3-small (512 dims) — 3x smaller than default 1536,
+// Uses OpenAI text-embedding-3-small (512 dims) - 3x smaller than default 1536,
 // same key as the rest of Daemora, no extra deps.
 // Falls back to keyword search if OPENAI_API_KEY is absent.
 
-// Patterns from adversarial testing — prevent memory from becoming a prompt-injection vector
+// Patterns from adversarial testing - prevent memory from becoming a prompt-injection vector
 const _INJECTION_PATTERNS = [
   /ignore (all|any|previous|above|prior) instructions/i,
   /do not follow (the )?(system|developer)/i,
@@ -97,7 +98,7 @@ function _loadEmbeddingsForPath(embeddingsPath) {
   try { return JSON.parse(readFileSync(embeddingsPath, "utf-8")); } catch { return []; }
 }
 
-// Standard cosine similarity — correct metric for text embeddings (unlike OpenClaw's L2)
+// Standard cosine similarity - correct metric for text embeddings (unlike OpenClaw's L2)
 function _cosineSim(a, b) {
   let dot = 0, na = 0, nb = 0;
   for (let i = 0; i < a.length; i++) {
@@ -109,22 +110,11 @@ function _cosineSim(a, b) {
   return dot / (Math.sqrt(na) * Math.sqrt(nb));
 }
 
-// Generate embedding using OpenAI text-embedding-3-small at 512 dims.
-// 512 dims = ~3x smaller JSON than default 1536, with minimal quality loss for recall.
-async function _generateEmbedding(text) {
-  if (!process.env.OPENAI_API_KEY) return null;
-  try {
-    const { default: OpenAI } = await import("openai");
-    const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-    const res = await client.embeddings.create({
-      model: "text-embedding-3-small",
-      input: text.slice(0, 8000),  // API hard limit
-      dimensions: 512,
-    });
-    return res.data[0].embedding;
-  } catch {
-    return null;
-  }
+// Delegate to shared provider-agnostic embedding utility.
+// Supports OpenAI, Google Gemini, and Ollama - auto-detected from available API keys.
+// Returns null if no provider configured → callers fall back to keyword search.
+function _generateEmbedding(text) {
+  return generateEmbedding(text);
 }
 
 // Store a new memory entry's embedding. Called as fire-and-forget from writeMemory.
@@ -140,7 +130,8 @@ async function _indexEntry(text, category, timestamp) {
     if (e.vector && _cosineSim(e.vector, vector) > 0.92) return;
   }
 
-  entries.push({ id: randomUUID(), timestamp, category: category || "general", text, vector });
+  const provider = getEmbeddingProvider() || "openai";
+  entries.push({ id: randomUUID(), timestamp, category: category || "general", text, vector, provider });
   _saveEmbeddings(entries);
 }
 
@@ -162,8 +153,9 @@ export async function getRelevantMemories(taskInput, topK = 5, tenantId = null)
   const entries = _loadEmbeddingsForPath(paths.embeddingsPath);
   if (entries.length === 0) return null;
 
+  const currentProvider = getEmbeddingProvider() || "openai";
   const scored = entries
-    .filter((e) => e.vector)
+    .filter((e) => e.vector && (e.provider === currentProvider || (!e.provider && currentProvider === "openai")))
     .map((e) => ({ ...e, score: _cosineSim(e.vector, queryVector) }))
     .filter((e) => e.score >= 0.40)
     .sort((a, b) => b.score - a.score)
@@ -248,7 +240,7 @@ export async function writeMemory(entry, category) {
   writeFileSync(memoryPath, existing + formatted, "utf-8");
   console.log(`      [memory] Entry added (${entry.length} chars)${category ? ` category=${category}` : ""}`);
 
-  // Generate and store embedding in background — does not block the tool response
+  // Generate and store embedding in background - does not block the tool response
   _indexEntry(entry, category, timestamp).catch(() => {});
 
   return `Memory saved${category ? ` [${category}]` : ""}: "${entry.slice(0, 80)}${entry.length > 80 ? "..." : ""}"`;
@@ -282,10 +274,10 @@ export function writeDailyLog(entry) {
   if (existsSync(logPath)) {
     existing = readFileSync(logPath, "utf-8");
   } else {
-    existing = `# Daily Log — ${today}\n\n`;
+    existing = `# Daily Log - ${today}\n\n`;
   }
 
-  const formatted = `- **${timestamp}** — ${entry.trim()}\n`;
+  const formatted = `- **${timestamp}** - ${entry.trim()}\n`;
   writeFileSync(logPath, existing + formatted, "utf-8");
 
   console.log(`      [memory] Daily log entry added`);
@@ -309,16 +301,17 @@ export async function searchMemory(query, optionsJson) {
   const mode           = opts.mode || "auto"; // "auto" | "semantic" | "keyword"
 
   // ── Semantic search (cosine similarity on stored embeddings) ─────────────────
-  if (mode !== "keyword" && process.env.OPENAI_API_KEY) {
+  if (mode !== "keyword" && getEmbeddingProvider()) {
     const queryVector = await _generateEmbedding(query);
     if (queryVector) {
+      const currentProvider = getEmbeddingProvider() || "openai";
       let entries = _loadEmbeddings();
       if (filterCategory) {
         entries = entries.filter((e) => e.category === filterCategory.toLowerCase());
       }
 
       const scored = entries
-        .filter((e) => e.vector)
+        .filter((e) => e.vector && (e.provider === currentProvider || (!e.provider && currentProvider === "openai")))
         .map((e) => ({ ...e, score: _cosineSim(e.vector, queryVector) }))
         .filter((e) => e.score >= minScore)
         .sort((a, b) => b.score - a.score)
@@ -329,12 +322,12 @@ export async function searchMemory(query, optionsJson) {
         const lines = scored.map(
           (e, i) =>
             `${i + 1}. [${e.category}] (${(e.score * 100).toFixed(0)}% match) ` +
-            `${_escapeForPrompt(e.text)}\n   — ${e.timestamp.split("T")[0]}`
+            `${_escapeForPrompt(e.text)}\n   - ${e.timestamp.split("T")[0]}`
         );
         return `Found ${scored.length} semantic match(es) for "${query}":\n\n${lines.join("\n")}`;
       }
 
-      // Nothing above threshold — fall through to keyword unless semantic-only requested
+      // Nothing above threshold - fall through to keyword unless semantic-only requested
       if (mode === "semantic") {
         return `No semantic matches found for "${query}" (threshold: ${minScore})`;
       }
@@ -399,7 +392,7 @@ export function pruneMemory(maxAgeDaysStr) {
   let prunedMemory = 0;
   let prunedLogs = 0;
 
-  // Prune MEMORY.md — keep entries newer than cutoff
+  // Prune MEMORY.md - keep entries newer than cutoff
   if (existsSync(memoryPath)) {
     const content = readFileSync(memoryPath, "utf-8");
     const entries = parseEntries(content);

package/src/tools/messageChannel.js

@@ -1,5 +1,5 @@
 /**
- * messageChannel(channel, target, message) — Send a message to any configured channel.
+ * messageChannel(channel, target, message) - Send a message to any configured channel.
  * Allows the agent to proactively message users, not just reply to inbound tasks.
  * Inspired by OpenClaw's message tool.
  */

package/src/tools/notification.js

@@ -0,0 +1,90 @@
+/**
+ * notification - Send desktop / mobile push notifications.
+ * macOS: osascript / terminal-notifier. Linux: notify-send. Windows: PowerShell.
+ * Cross-platform mobile: Pushover, Pushbullet, Ntfy.sh.
+ */
+import { execSync } from "node:child_process";
+
+function platform() { return process.platform; }
+
+export async function notification(title, message, options = {}) {
+  if (!title) return "Error: title is required";
+  if (!message) return "Error: message is required";
+
+  const opts = typeof options === "string" ? JSON.parse(options) : (options || {});
+  const { sound = false, url = null, service = "desktop", topic = null } = opts;
+
+  // ── Desktop notification ────────────────────────────────────────────────
+  if (service === "desktop") {
+    try {
+      if (platform() === "darwin") {
+        // Use osascript for macOS (built-in, no deps)
+        const script = `display notification ${JSON.stringify(message)} with title ${JSON.stringify(title)}${sound ? " sound name \"Glass\"" : ""}`;
+        execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, { timeout: 5000 });
+        return `Notification sent: "${title}"`;
+      } else if (platform() === "linux") {
+        const urgency = opts.urgency || "normal";
+        const expireMs = opts.expireMs || 5000;
+        execSync(`notify-send -u ${urgency} -t ${expireMs} ${JSON.stringify(title)} ${JSON.stringify(message)}`, { timeout: 5000 });
+        return `Notification sent: "${title}"`;
+      } else if (platform() === "win32") {
+        const ps = `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null; $template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02); $template.SelectSingleNode('//text[@id=1]').AppendChild($template.CreateTextNode('${title.replace(/'/g, "''")}')) > $null; $template.SelectSingleNode('//text[@id=2]').AppendChild($template.CreateTextNode('${message.replace(/'/g, "''")}')) > $null; $toast = [Windows.UI.Notifications.ToastNotification]::new($template); [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Daemora').Show($toast)`;
+        execSync(`powershell -Command "${ps}"`, { timeout: 5000 });
+        return `Notification sent: "${title}"`;
+      } else {
+        return "Error: desktop notifications not supported on this platform";
+      }
+    } catch (err) {
+      return `Notification error: ${err.message}`;
+    }
+  }
+
+  // ── Ntfy.sh (HTTP push — open source, self-hostable) ───────────────────
+  if (service === "ntfy") {
+    const ntfyUrl = process.env.NTFY_URL || "https://ntfy.sh";
+    const ntfyTopic = topic || process.env.NTFY_TOPIC;
+    if (!ntfyTopic) return "Error: NTFY_TOPIC env var or topic option required for ntfy service";
+
+    const { default: fetch } = await import("node-fetch").catch(() => ({ default: globalThis.fetch }));
+    const res = await fetch(`${ntfyUrl}/${ntfyTopic}`, {
+      method: "POST",
+      body: message,
+      headers: {
+        "Title": title,
+        ...(url ? { "Click": url } : {}),
+        ...(process.env.NTFY_TOKEN ? { "Authorization": `Bearer ${process.env.NTFY_TOKEN}` } : {}),
+      },
+    });
+    if (!res.ok) return `Ntfy error: ${res.status} ${await res.text()}`;
+    return `Ntfy notification sent to topic "${ntfyTopic}": "${title}"`;
+  }
+
+  // ── Pushover ────────────────────────────────────────────────────────────
+  if (service === "pushover") {
+    const token = process.env.PUSHOVER_API_TOKEN;
+    const user = process.env.PUSHOVER_USER_KEY;
+    if (!token || !user) return "Error: PUSHOVER_API_TOKEN and PUSHOVER_USER_KEY env vars required";
+
+    const body = new URLSearchParams({ token, user, title, message });
+    if (url) body.set("url", url);
+
+    const { default: fetch } = await import("node-fetch").catch(() => ({ default: globalThis.fetch }));
+    const res = await fetch("https://api.pushover.net/1/messages.json", { method: "POST", body });
+    const data = await res.json();
+    if (data.status !== 1) return `Pushover error: ${JSON.stringify(data.errors)}`;
+    return `Pushover notification sent: "${title}"`;
+  }
+
+  return `Unknown service: "${service}". Valid: desktop, ntfy, pushover`;
+}
+
+export const notificationDescription =
+  `notification(title: string, message: string, options?: object) - Send desktop or push notifications.
+  options.service: "desktop" (default) | "ntfy" | "pushover"
+  options.sound: boolean (macOS only, plays Glass sound)
+  options.url: URL to open on click (ntfy/pushover)
+  options.topic: ntfy topic name (or set NTFY_TOPIC env)
+  Env vars: NTFY_URL, NTFY_TOPIC, NTFY_TOKEN, PUSHOVER_API_TOKEN, PUSHOVER_USER_KEY
+  Examples:
+    notification("Task done", "Your report is ready")               → desktop alert
+    notification("Alert", "Server down", {"service":"ntfy","topic":"myalerts"})`;

package/src/tools/philipsHue.js

@@ -0,0 +1,147 @@
+/**
+ * philipsHue - Control Philips Hue smart lights via local Bridge API.
+ * Requires HUE_BRIDGE_IP and HUE_API_KEY env vars.
+ * All requests go to the local bridge — no cloud dependency.
+ */
+
+export async function philipsHue(action, paramsJson) {
+  if (!action) return "Error: action required. Valid: list, on, off, color, brightness, scene, discover";
+  const params = paramsJson
+    ? (typeof paramsJson === "string" ? JSON.parse(paramsJson) : paramsJson)
+    : {};
+
+  const bridgeIp = params.bridgeIp || process.env.HUE_BRIDGE_IP;
+  const apiKey = params.apiKey || process.env.HUE_API_KEY;
+
+  // Discovery doesn't require credentials
+  if (action === "discover") {
+    const fetchFn = globalThis.fetch || (await import("node-fetch")).default;
+    try {
+      const res = await fetchFn("https://discovery.meethue.com/");
+      const data = await res.json();
+      if (!data.length) return "No Hue bridges found on network";
+      return data.map(b => `Bridge: ${b.id} at ${b.internalipaddress}`).join("\n");
+    } catch (err) {
+      return `Discovery error: ${err.message}`;
+    }
+  }
+
+  if (!bridgeIp) return "Error: HUE_BRIDGE_IP env var or bridgeIp param required";
+  if (!apiKey) return "Error: HUE_API_KEY env var or apiKey param required";
+
+  const BASE = `http://${bridgeIp}/api/${apiKey}`;
+  const fetchFn = globalThis.fetch || (await import("node-fetch")).default;
+
+  const hueReq = async (method, path, body = null) => {
+    const opts = { method, headers: { "Content-Type": "application/json" } };
+    if (body) opts.body = JSON.stringify(body);
+    const res = await fetchFn(`${BASE}${path}`, opts);
+    return res.json();
+  };
+
+  if (action === "list") {
+    const data = await hueReq("GET", "/lights");
+    if (!data || typeof data !== "object") return "Error reading lights";
+    const entries = Object.entries(data);
+    if (!entries.length) return "No lights found";
+    return entries.map(([id, light]) =>
+      `[${id}] ${light.name} — ${light.state.on ? "ON" : "OFF"} — brightness: ${light.state.bri || "N/A"} — ${light.state.reachable ? "reachable" : "unreachable"}`
+    ).join("\n");
+  }
+
+  const { lightId, groupId } = params;
+  const targetPath = groupId
+    ? `/groups/${groupId}/action`
+    : lightId
+    ? `/lights/${lightId}/state`
+    : null;
+
+  if (action === "on") {
+    if (!targetPath) return "Error: lightId or groupId required";
+    await hueReq("PUT", targetPath, { on: true });
+    return `Light ${lightId || `group ${groupId}`} turned ON`;
+  }
+
+  if (action === "off") {
+    if (!targetPath) return "Error: lightId or groupId required";
+    await hueReq("PUT", targetPath, { on: false });
+    return `Light ${lightId || `group ${groupId}`} turned OFF`;
+  }
+
+  if (action === "brightness") {
+    if (!targetPath) return "Error: lightId or groupId required";
+    const { level } = params;
+    if (level === undefined) return "Error: level (0-254) required";
+    const bri = Math.max(0, Math.min(254, Math.round(level)));
+    await hueReq("PUT", targetPath, { on: true, bri });
+    return `Brightness set to ${level} for light ${lightId || `group ${groupId}`}`;
+  }
+
+  if (action === "color") {
+    if (!targetPath) return "Error: lightId or groupId required";
+    const { hue, sat, bri, xy, colorTemp, hex } = params;
+
+    let state = { on: true };
+
+    if (hex) {
+      // Convert hex to XY (approximate using CIE 1931 color space)
+      const r = parseInt(hex.slice(1, 3), 16) / 255;
+      const g = parseInt(hex.slice(3, 5), 16) / 255;
+      const b = parseInt(hex.slice(5, 7), 16) / 255;
+      // Gamma correction
+      const toLinear = c => c > 0.04045 ? Math.pow((c + 0.055) / 1.055, 2.4) : c / 12.92;
+      const rL = toLinear(r), gL = toLinear(g), bL = toLinear(b);
+      const X = rL * 0.664511 + gL * 0.154324 + bL * 0.162028;
+      const Y = rL * 0.283881 + gL * 0.668433 + bL * 0.047685;
+      const Z = rL * 0.000088 + gL * 0.072310 + bL * 0.986039;
+      const sum = X + Y + Z || 1;
+      state.xy = [X / sum, Y / sum];
+      state.bri = Math.round(Y * 254);
+    } else if (xy) {
+      state.xy = xy;
+    } else if (hue !== undefined) {
+      state.hue = hue;
+      if (sat !== undefined) state.sat = sat;
+      if (bri !== undefined) state.bri = bri;
+    } else if (colorTemp !== undefined) {
+      state.ct = colorTemp; // Mired color temperature (153=cool, 500=warm)
+    } else {
+      return "Error: provide hex, xy, hue/sat, or colorTemp";
+    }
+
+    await hueReq("PUT", targetPath, state);
+    return `Color set for light ${lightId || `group ${groupId}`}`;
+  }
+
+  if (action === "scene") {
+    const { sceneId } = params;
+    const gId = groupId || "0";
+    if (!sceneId) {
+      // List scenes
+      const data = await hueReq("GET", "/scenes");
+      const entries = Object.entries(data || {});
+      if (!entries.length) return "No scenes found";
+      return entries.map(([id, s]) => `[${id}] ${s.name}`).join("\n");
+    }
+    await hueReq("PUT", `/groups/${gId}/action`, { scene: sceneId });
+    return `Scene "${sceneId}" activated`;
+  }
+
+  return `Unknown action: "${action}". Valid: list, on, off, brightness, color, scene, discover`;
+}
+
+export const philipsHueDescription =
+  `philipsHue(action: string, paramsJson?: object) - Control Philips Hue smart lights via local bridge.
+  action: "list" | "on" | "off" | "brightness" | "color" | "scene" | "discover"
+  list: {} → shows all lights with status
+  on/off: { lightId?: "1", groupId?: "1" }
+  brightness: { lightId, level: 0-254 }
+  color: { lightId, hex?: "#ff6600" | hue?: 0-65535, sat?: 0-254 | xy?: [x,y] | colorTemp?: 153-500 }
+  scene: { groupId?, sceneId? } (omit sceneId to list scenes)
+  discover: {} → finds bridges on local network
+  Env vars: HUE_BRIDGE_IP, HUE_API_KEY
+  Examples:
+    philipsHue("list")
+    philipsHue("on", {"lightId":"1"})
+    philipsHue("color", {"lightId":"2","hex":"#ff6600"})
+    philipsHue("brightness", {"groupId":"1","level":128})`;

package/src/tools/projectTracker.js

@@ -6,18 +6,18 @@ import { v4 as uuidv4 } from "uuid";
 const WORKSPACES_DIR = join(config.dataDir, "workspaces");
 
 /**
- * Project Tracker — SQLite-equivalent task/project tracking for the agent.
+ * Project Tracker - SQLite-equivalent task/project tracking for the agent.
  *
  * The agent uses this to plan multi-step work, track what's done vs pending,
  * and resume from where it left off if interrupted.
  *
  * Actions:
- *   createProject  — create a project with optional initial task list
- *   addTask        — add a task to an existing project
- *   updateTask     — mark a task as in_progress / done / failed / skipped
- *   getProject     — full status of one project (what's done, what's pending)
- *   listProjects   — all projects with summary
- *   deleteProject  — remove a completed/stale project
+ *   createProject  - create a project with optional initial task list
+ *   addTask        - add a task to an existing project
+ *   updateTask     - mark a task as in_progress / done / failed / skipped
+ *   getProject     - full status of one project (what's done, what's pending)
+ *   listProjects   - all projects with summary
+ *   deleteProject  - remove a completed/stale project
  *
  * Storage: data/projects/<id>.json  (JSON files, no external deps)
  */
@@ -97,7 +97,7 @@ export function projectTracker(action, paramsJson) {
 
       const taskList = project.tasks.length > 0
         ? project.tasks.map(t => `  ${STATUS_ICON.pending} [${t.id}] ${t.title}`).join("\n")
-        : "  (no tasks yet — use addTask to add them)";
+        : "  (no tasks yet - use addTask to add them)";
 
       return `Project created: ${project.id}\nName: ${name}${description ? `\nDescription: ${description}` : ""}\nWorkspace: ${workspace}\nTasks (${project.tasks.length}):\n${taskList}`;
     }

package/src/tools/readFile.js

@@ -40,7 +40,7 @@ export function readFile(filePath, offsetStr, limitStr) {
       result += `\n\n[... ${totalLines - endIdx} more lines. Use offset=${endIdx + 1} to continue reading.]`;
     }
 
-    console.log(`      [readFile] Done — showing lines ${startIdx + 1}-${endIdx} of ${totalLines}`);
+    console.log(`      [readFile] Done - showing lines ${startIdx + 1}-${endIdx} of ${totalLines}`);
     return result;
   } catch (error) {
     console.log(`      [readFile] Failed: ${error.message}`);

package/src/tools/readPDF.js

@@ -0,0 +1,73 @@
+/**
+ * readPDF - Extract text content from a PDF file.
+ * Uses pdftotext (poppler) if available, falls back to OpenAI vision API.
+ */
+import { execSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import filesystemGuard from "../safety/FilesystemGuard.js";
+import tenantContext from "../tenants/TenantContext.js";
+
+export async function readPDF(filePath, optionsJson) {
+  if (!filePath) return "Error: filePath is required.";
+
+  const guard = filesystemGuard.checkRead(filePath);
+  if (!guard.allowed) return `Access denied: ${guard.reason}`;
+  if (!existsSync(filePath)) return `Error: File not found: ${filePath}`;
+
+  let opts = {};
+  if (optionsJson) { try { opts = JSON.parse(optionsJson); } catch {} }
+  const { pages = null, method = "auto" } = opts;
+
+  // Method 1: pdftotext (poppler-utils) — fast, no API cost
+  if (method === "auto" || method === "pdftotext") {
+    try {
+      const pageFlag = pages ? `-f ${pages.split("-")[0]} -l ${pages.split("-")[1] || pages.split("-")[0]}` : "";
+      const text = execSync(`pdftotext ${pageFlag} "${filePath}" -`, { encoding: "utf-8", timeout: 30000 });
+      if (text.trim()) return text.trim();
+    } catch {
+      // pdftotext not available, fall through
+    }
+  }
+
+  // Method 2: OpenAI vision API — works without pdftotext installed
+  if (method === "auto" || method === "vision") {
+    const store = tenantContext.getStore();
+    const apiKey = store?.apiKeys?.OPENAI_API_KEY || process.env.OPENAI_API_KEY;
+    if (!apiKey) return "Error: pdftotext not found and OPENAI_API_KEY not set. Install poppler-utils or set OPENAI_API_KEY.";
+
+    try {
+      const fileBytes = readFileSync(filePath);
+      const b64 = fileBytes.toString("base64");
+      const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({
+          model: "gpt-4o",
+          messages: [{
+            role: "user",
+            content: [
+              { type: "text", text: "Extract all text content from this PDF. Return only the text, preserve structure." },
+              { type: "image_url", image_url: { url: `data:application/pdf;base64,${b64}` } },
+            ],
+          }],
+          max_tokens: 4096,
+        }),
+      });
+      const data = await res.json();
+      if (!res.ok) return `Error: ${data.error?.message || res.status}`;
+      return data.choices?.[0]?.message?.content || "No text extracted.";
+    } catch (err) {
+      return `Error extracting PDF: ${err.message}`;
+    }
+  }
+
+  return "Error: No extraction method available. Install poppler-utils (brew install poppler) or set OPENAI_API_KEY.";
+}
+
+export const readPDFDescription =
+  `readPDF(filePath: string, optionsJson?: string) - Extract text from a PDF file.
+  filePath: path to the PDF file
+  optionsJson: {"pages":"1-5","method":"auto"}
+  method: "auto" (pdftotext first, then vision), "pdftotext", "vision"
+  pages: page range like "1-5" (pdftotext only)
+  Returns extracted text content.`;