daemora 1.0.1 → 1.0.3

package/src/tools/googlePlaces.js

@@ -0,0 +1,136 @@
+/**
+ * googlePlaces - Search and get details from Google Places API.
+ * Requires GOOGLE_PLACES_API_KEY env var.
+ */
+
+export async function googlePlaces(action, paramsJson) {
+  if (!action) return "Error: action required. Valid: search, details, nearby, autocomplete";
+  const params = paramsJson
+    ? (typeof paramsJson === "string" ? JSON.parse(paramsJson) : paramsJson)
+    : {};
+
+  const apiKey = params.apiKey || process.env.GOOGLE_PLACES_API_KEY;
+  if (!apiKey) return "Error: GOOGLE_PLACES_API_KEY env var required";
+
+  const fetchFn = globalThis.fetch || (await import("node-fetch")).default;
+  const BASE = "https://maps.googleapis.com/maps/api";
+
+  if (action === "search") {
+    const { query, location, radius = 5000, type } = params;
+    if (!query) return "Error: query is required";
+
+    const qs = new URLSearchParams({
+      query,
+      key: apiKey,
+      ...(location ? { location } : {}),
+      ...(radius ? { radius: String(radius) } : {}),
+      ...(type ? { type } : {}),
+    });
+
+    const res = await fetchFn(`${BASE}/place/textsearch/json?${qs}`);
+    const data = await res.json();
+    if (data.status !== "OK" && data.status !== "ZERO_RESULTS") {
+      return `Places API error: ${data.status} — ${data.error_message || ""}`;
+    }
+    if (!data.results?.length) return `No places found for "${query}"`;
+
+    return data.results.slice(0, params.limit || 5).map(p => [
+      `Name: ${p.name}`,
+      `Address: ${p.formatted_address}`,
+      `Rating: ${p.rating || "N/A"} (${p.user_ratings_total || 0} reviews)`,
+      `Place ID: ${p.place_id}`,
+      p.opening_hours?.open_now !== undefined ? `Open now: ${p.opening_hours.open_now}` : "",
+    ].filter(Boolean).join("\n")).join("\n\n");
+  }
+
+  if (action === "details") {
+    const { placeId, fields = "name,formatted_address,formatted_phone_number,website,rating,opening_hours,reviews" } = params;
+    if (!placeId) return "Error: placeId is required";
+
+    const qs = new URLSearchParams({ place_id: placeId, fields, key: apiKey });
+    const res = await fetchFn(`${BASE}/place/details/json?${qs}`);
+    const data = await res.json();
+    if (data.status !== "OK") return `Places details error: ${data.status}`;
+
+    const r = data.result;
+    const lines = [
+      `Name: ${r.name}`,
+      `Address: ${r.formatted_address}`,
+      r.formatted_phone_number ? `Phone: ${r.formatted_phone_number}` : null,
+      r.website ? `Website: ${r.website}` : null,
+      r.rating ? `Rating: ${r.rating}/5 (${r.user_ratings_total} reviews)` : null,
+    ].filter(Boolean);
+
+    if (r.opening_hours?.weekday_text) {
+      lines.push("Hours:\n" + r.opening_hours.weekday_text.map(h => `  ${h}`).join("\n"));
+    }
+
+    if (r.reviews?.length && params.includeReviews) {
+      lines.push("Top reviews:");
+      r.reviews.slice(0, 3).forEach(rev => {
+        lines.push(`  ⭐${rev.rating} — ${rev.author_name}: "${rev.text?.slice(0, 100)}..."`);
+      });
+    }
+
+    return lines.join("\n");
+  }
+
+  if (action === "nearby") {
+    const { location, radius = 1000, type } = params;
+    if (!location) return "Error: location is required (e.g. '37.7749,-122.4194')";
+
+    const qs = new URLSearchParams({
+      location,
+      radius: String(radius),
+      key: apiKey,
+      ...(type ? { type } : {}),
+    });
+
+    const res = await fetchFn(`${BASE}/place/nearbysearch/json?${qs}`);
+    const data = await res.json();
+    if (data.status !== "OK" && data.status !== "ZERO_RESULTS") {
+      return `Nearby search error: ${data.status}`;
+    }
+    if (!data.results?.length) return "No places found nearby";
+
+    return data.results.slice(0, params.limit || 5).map(p =>
+      `${p.name} — ${p.vicinity} (Rating: ${p.rating || "N/A"})`
+    ).join("\n");
+  }
+
+  if (action === "autocomplete") {
+    const { input, location, radius } = params;
+    if (!input) return "Error: input is required";
+
+    const qs = new URLSearchParams({
+      input,
+      key: apiKey,
+      ...(location ? { location } : {}),
+      ...(radius ? { radius: String(radius) } : {}),
+    });
+
+    const res = await fetchFn(`${BASE}/place/autocomplete/json?${qs}`);
+    const data = await res.json();
+    if (data.status !== "OK" && data.status !== "ZERO_RESULTS") {
+      return `Autocomplete error: ${data.status}`;
+    }
+    if (!data.predictions?.length) return `No suggestions for "${input}"`;
+
+    return data.predictions.map(p => `${p.description} (${p.place_id})`).join("\n");
+  }
+
+  return `Unknown action: "${action}". Valid: search, details, nearby, autocomplete`;
+}
+
+export const googlePlacesDescription =
+  `googlePlaces(action: string, paramsJson?: object) - Search places, get details, find nearby locations.
+  action: "search" | "details" | "nearby" | "autocomplete"
+  search params: { query, location?: "lat,lng", radius?: 5000, type?, limit?: 5 }
+  details params: { placeId, fields?, includeReviews?: false }
+  nearby params: { location: "lat,lng", radius?: 1000, type?, limit?: 5 }
+  autocomplete params: { input, location?, radius? }
+  Env var: GOOGLE_PLACES_API_KEY
+  Examples:
+    googlePlaces("search", {"query":"coffee shops in San Francisco"})
+    googlePlaces("nearby", {"location":"37.7749,-122.4194","radius":500,"type":"restaurant"})
+    googlePlaces("details", {"placeId":"ChIJN1t_tDeuEmsRUsoyG83frY4"})`;

package/src/tools/grep.js

@@ -1,6 +1,6 @@
 /**
- * grep(pattern, optionsJson?) — Advanced content search with context lines.
- * Inspired by Claude Code's Grep tool. Pure Node.js — no shell dependency.
+ * grep(pattern, optionsJson?) - Advanced content search with context lines.
+ * Inspired by Claude Code's Grep tool. Pure Node.js - no shell dependency.
  */
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, extname, relative } from "node:path";

package/src/tools/iMessageTool.js

@@ -0,0 +1,86 @@
+/**
+ * iMessageTool - Send iMessages and SMS via macOS Messages app.
+ * Requires macOS with Messages app configured and accessibility permissions.
+ * Uses osascript (AppleScript) — no external deps.
+ */
+import { execSync } from "node:child_process";
+
+export async function iMessageTool(action, paramsJson) {
+  if (!action) return "Error: action required. Valid: send, read";
+  const params = paramsJson
+    ? (typeof paramsJson === "string" ? JSON.parse(paramsJson) : paramsJson)
+    : {};
+
+  if (process.platform !== "darwin") {
+    return "Error: iMessage tool is macOS-only (requires Messages app via AppleScript)";
+  }
+
+  if (action === "send") {
+    const { to, message, service = "iMessage" } = params;
+    if (!to) return "Error: 'to' (phone number or email) is required";
+    if (!message) return "Error: 'message' is required";
+
+    // Validate service type
+    const validServices = ["iMessage", "SMS"];
+    if (!validServices.includes(service)) {
+      return `Error: invalid service "${service}". Valid: iMessage, SMS`;
+    }
+
+    const script = `
+      tell application "Messages"
+        set targetService to 1st service whose service type = ${service}
+        set targetBuddy to buddy "${to.replace(/"/g, '\\"')}" of targetService
+        send "${message.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}" to targetBuddy
+      end tell
+    `;
+
+    try {
+      execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, { timeout: 10000 });
+      return `${service} sent to ${to}: "${message.length > 60 ? message.slice(0, 60) + "..." : message}"`;
+    } catch (err) {
+      return `iMessage error: ${err.message}. Make sure Messages app is open and has the contact.`;
+    }
+  }
+
+  if (action === "read") {
+    const { count = 10 } = params;
+    // AppleScript to read recent messages
+    const script = `
+      tell application "Messages"
+        set output to ""
+        set allChats to chats
+        repeat with aChat in allChats
+          set msgCount to count of messages of aChat
+          if msgCount > 0 then
+            set lastMsg to last message of aChat
+            set output to output & name of aChat & ": " & content of lastMsg & "\\n"
+          end if
+        end repeat
+        return output
+      end tell
+    `;
+
+    try {
+      const result = execSync(`osascript -e '${script.replace(/'/g, "\\'")}'`, {
+        encoding: "utf-8",
+        timeout: 10000,
+      });
+      if (!result.trim()) return "No recent messages found";
+      return `Recent messages:\n${result.trim()}`;
+    } catch (err) {
+      return `Error reading messages: ${err.message}`;
+    }
+  }
+
+  return `Unknown action: "${action}". Valid: send, read`;
+}
+
+export const iMessageToolDescription =
+  `iMessageTool(action: string, paramsJson?: object) - Send and read iMessages/SMS on macOS.
+  action: "send" | "read"
+  send params: { to: "+1234567890"|"email@icloud.com", message: "text", service?: "iMessage"|"SMS" }
+  read params: { count?: 10 }
+  Requires: macOS with Messages app configured + Accessibility permissions for osascript
+  Examples:
+    iMessageTool("send", {"to":"+15551234567","message":"Hello!"})
+    iMessageTool("read", {"count":5})`;

package/src/tools/imageAnalysis.js

@@ -1,5 +1,5 @@
 /**
- * imageAnalysis(imagePath, prompt?) — Analyze images using vision AI models.
+ * imageAnalysis(imagePath, prompt?) - Analyze images using vision AI models.
  * Supports local files, URLs, and data: URIs.
  * Uses the Vercel AI SDK with whatever vision-capable model is configured.
  */
@@ -38,13 +38,13 @@ export async function imageAnalysis(imagePath, prompt) {
     }
 
     if (imagePath.startsWith("data:")) {
-      // data: URI — extract base64 and mime type
+      // data: URI - extract base64 and mime type
       const match = imagePath.match(/^data:([^;]+);base64,(.+)$/);
       if (!match) return "Error: Invalid data: URI format";
       mimeType = match[1];
       imageData = match[2];
     } else if (imagePath.startsWith("http://") || imagePath.startsWith("https://")) {
-      // URL — fetch and convert to base64
+      // URL - fetch and convert to base64
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), 15000);
       try {

package/src/tools/index.js

@@ -28,7 +28,7 @@ import { transcribeAudio, transcribeAudioDescription } from "./transcribeAudio.j
 import { sendFile, sendFileDescription } from "./sendFile.js";
 import { textToSpeech, textToSpeechDescription } from "./textToSpeech.js";
 
-// ─── New tools ─────────────────────────────────────────────────────────────────
+// ─── Search & code tools ───────────────────────────────────────────────────────
 import { globSearch, globSearchDescription } from "./glob.js";
 import { grep, grepDescription } from "./grep.js";
 import { applyPatch, applyPatchDescription } from "./applyPatch.js";
@@ -40,6 +40,22 @@ import { messageChannel, messageChannelDescription } from "./messageChannel.js";
 import { projectTracker, projectTrackerDescription } from "./projectTracker.js";
 import { manageMCP, manageMCPDescription } from "./manageMCP.js";
 import { useMCP, useMCPDescription } from "./useMCP.js";
+import { makeVoiceCall, makeVoiceCallDescription } from "./makeVoiceCall.js";
+
+// ─── Phase 24 tools ────────────────────────────────────────────────────────────
+import { generateImage, generateImageDescription } from "./generateImage.js";
+import { readPDF, readPDFDescription } from "./readPDF.js";
+import { gitTool, gitToolDescription } from "./gitTool.js";
+import { clipboard, clipboardDescription } from "./clipboard.js";
+import { notification, notificationDescription } from "./notification.js";
+import { iMessageTool, iMessageToolDescription } from "./iMessageTool.js";
+import { calendar, calendarDescription } from "./calendar.js";
+import { sshTool, sshToolDescription } from "./sshTool.js";
+import { database, databaseDescription } from "./database.js";
+import { contacts, contactsDescription } from "./contacts.js";
+import { googlePlaces, googlePlacesDescription } from "./googlePlaces.js";
+import { philipsHue, philipsHueDescription } from "./philipsHue.js";
+import { sonos, sonosDescription } from "./sonos.js";
 
 // ─── Wrap spawnAgent for the tool interface ────────────────────────────────────
 function spawnAgent(taskDescription, optionsJson) {
@@ -74,7 +90,7 @@ export const toolFunctions = {
   listDirectory,
   searchFiles,
   searchContent,
-  // Advanced search (new)
+  // Advanced search
   glob: globSearch,
   grep,
   applyPatch,
@@ -116,6 +132,25 @@ export const toolFunctions = {
   // MCP management
   manageMCP,
   useMCP,
+  // Voice
+  makeVoiceCall,
+  // Phase 24: Image & document
+  generateImage,
+  readPDF,
+  // Phase 24: Developer tools
+  gitTool,
+  clipboard,
+  sshTool,
+  database,
+  // Phase 24: macOS / notifications
+  notification,
+  iMessageTool,
+  calendar,
+  contacts,
+  // Phase 24: External services
+  googlePlaces,
+  philipsHue,
+  sonos,
 };
 
 // ─── Tool Descriptions Array ───────────────────────────────────────────────────
@@ -170,4 +205,23 @@ export const toolDescriptions = [
   // MCP management
   manageMCPDescription,
   useMCPDescription,
+  // Voice
+  makeVoiceCallDescription,
+  // Phase 24: Image & document
+  generateImageDescription,
+  readPDFDescription,
+  // Phase 24: Developer tools
+  gitToolDescription,
+  clipboardDescription,
+  sshToolDescription,
+  databaseDescription,
+  // Phase 24: macOS / notifications
+  notificationDescription,
+  iMessageToolDescription,
+  calendarDescription,
+  contactsDescription,
+  // Phase 24: External services
+  googlePlacesDescription,
+  philipsHueDescription,
+  sonosDescription,
 ];

package/src/tools/makeVoiceCall.js

@@ -0,0 +1,283 @@
+/**
+ * makeVoiceCall - Interactive outbound voice calls via Twilio REST API.
+ *
+ * Supports two modes:
+ *
+ *   ONE-SHOT: initiate a call that plays a message and hangs up
+ *     makeVoiceCall("call", "+1555...", {"message":"Your order is ready"})
+ *
+ *   INTERACTIVE: full two-way conversation — agent speaks, listens, responds
+ *     makeVoiceCall("initiate", "+1555...", {"greeting":"Hi, how can I help?"})
+ *     makeVoiceCall("listen",   sessionId)                   ← blocks until caller speaks
+ *     makeVoiceCall("speak",    sessionId, {"message":"..."}) ← agent says something
+ *     makeVoiceCall("end",      sessionId)                   ← hang up
+ *
+ * Credential resolution order (first match wins):
+ *   1. Per-tenant channel config  (daemora tenant channel set <id> twilio_account_sid ...)
+ *   2. Global .env                (TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN / TWILIO_PHONE_FROM)
+ *
+ * Required env for interactive mode:
+ *   VOICE_WEBHOOK_BASE_URL=https://your-public-url.com  (Twilio must reach this URL)
+ */
+
+import tenantContext from "../tenants/TenantContext.js";
+import voiceSessionManager from "../voice/VoiceSessionManager.js";
+
+const TWILIO_API = "https://api.twilio.com/2010-04-01";
+
+/** Resolve Twilio credentials: tenant config first, then global env */
+function _getCreds() {
+  const store = tenantContext.getStore();
+  const ch = store?.resolvedConfig?.channelConfig || {};
+
+  return {
+    accountSid: ch.twilio_account_sid || process.env.TWILIO_ACCOUNT_SID || null,
+    authToken:  ch.twilio_auth_token  || process.env.TWILIO_AUTH_TOKEN  || null,
+    fromNumber: ch.twilio_phone_from  || process.env.TWILIO_PHONE_FROM  || null,
+  };
+}
+
+/** Make an authenticated Twilio REST request */
+async function _twilioRequest(accountSid, authToken, method, path, body = null) {
+  const url = `${TWILIO_API}/Accounts/${accountSid}${path}`;
+  const headers = {
+    Authorization: "Basic " + Buffer.from(`${accountSid}:${authToken}`).toString("base64"),
+    Accept: "application/json",
+  };
+  const opts = { method, headers };
+
+  if (body) {
+    opts.headers["Content-Type"] = "application/x-www-form-urlencoded";
+    opts.body = new URLSearchParams(body).toString();
+  }
+
+  const res = await fetch(url, opts);
+  const text = await res.text();
+  try {
+    return { ok: res.ok, status: res.status, data: JSON.parse(text) };
+  } catch {
+    return { ok: res.ok, status: res.status, data: { message: text } };
+  }
+}
+
+/** Build simple one-shot TwiML (speak a message, hang up) */
+function _buildSayTwiML(message, voice = "Polly.Joanna", language = "en-US") {
+  const escaped = message
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+  return `<?xml version="1.0" encoding="UTF-8"?><Response><Say voice="${voice}" language="${language}">${escaped}</Say></Response>`;
+}
+
+// ─── Main tool function ────────────────────────────────────────────────────────
+
+export async function makeVoiceCall(action, phoneNumberOrSessionId, optionsJson) {
+  if (!action) return 'Error: action required. Use: initiate|listen|speak|end|status|list  (or "call" for one-shot)';
+
+  const { accountSid, authToken, fromNumber } = _getCreds();
+
+  // ── Non-Twilio session actions (don't need credentials) ─────────────────────
+  // listen / speak / end operate on an existing session
+
+  if (action === "listen") {
+    const sessionId = phoneNumberOrSessionId;
+    if (!sessionId) return "Error: provide the session ID returned by initiate.";
+    const session = voiceSessionManager.get(sessionId);
+    if (!session) return `Error: No active session "${sessionId}". Did the call end?`;
+    if (session.status === "ended") return "Call has already ended.";
+
+    let opts = {};
+    if (optionsJson) { try { opts = JSON.parse(optionsJson); } catch {} }
+    const timeout = (opts.timeout || 120) * 1000;
+
+    try {
+      const text = await session.waitForCallerInput(timeout);
+      return `Caller said: "${text}"`;
+    } catch (err) {
+      return `${err.message}`;
+    }
+  }
+
+  if (action === "speak") {
+    const sessionId = phoneNumberOrSessionId;
+    if (!sessionId) return "Error: provide the session ID returned by initiate.";
+    const session = voiceSessionManager.get(sessionId);
+    if (!session) return `Error: No active session "${sessionId}".`;
+    if (session.status === "ended") return "Call has already ended.";
+
+    let opts = {};
+    if (optionsJson) { try { opts = JSON.parse(optionsJson); } catch {} }
+    const message = opts.message;
+    if (!message) return 'Error: optionsJson {"message":"..."} is required for speak.';
+
+    session.setAgentResponse(message);
+    return `Speaking to caller: "${message}"`;
+  }
+
+  if (action === "end") {
+    const sessionId = phoneNumberOrSessionId;
+    if (!sessionId) return "Error: provide the session ID returned by initiate.";
+    const session = voiceSessionManager.get(sessionId);
+    if (!session) return `Error: No active session "${sessionId}".`;
+
+    session.setAgentResponse("__HANGUP__");
+    return `Ending call for session ${sessionId}.`;
+  }
+
+  if (action === "status") {
+    const sessionId = phoneNumberOrSessionId;
+    const session = voiceSessionManager.get(sessionId);
+    if (!session) return `No active session "${sessionId}".`;
+
+    const turns = session.transcript.length;
+    const lastEntry = session.transcript[turns - 1];
+    const lastTurn = lastEntry ? ` | Last: [${lastEntry.role}] "${lastEntry.text.slice(0, 60)}"` : "";
+    return `Session ${session.id} | Status: ${session.status} | Turns: ${turns}${lastTurn}`;
+  }
+
+  // ── Twilio API actions — credentials required ────────────────────────────────
+
+  if (!accountSid || !authToken) {
+    return "Error: Twilio not configured. Set TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN in .env, or: daemora tenant channel set <id> twilio_account_sid <sid>";
+  }
+
+  let opts = {};
+  if (optionsJson) { try { opts = JSON.parse(optionsJson); } catch { return "Error: optionsJson must be valid JSON."; } }
+
+  // ── initiate — start an interactive call ────────────────────────────────────
+  if (action === "initiate") {
+    const to = phoneNumberOrSessionId;
+    if (!to) return "Error: phoneNumber is required for initiate.";
+    const from = opts.from || fromNumber;
+    if (!from) return 'Error: No outbound number. Set TWILIO_PHONE_FROM in .env or pass optionsJson {"from":"+1555..."}';
+
+    const webhookBase = process.env.VOICE_WEBHOOK_BASE_URL?.replace(/\/$/, "");
+    if (!webhookBase) {
+      return "Error: VOICE_WEBHOOK_BASE_URL not set. Set it to your public URL (e.g. https://myagent.example.com) so Twilio can reach the webhooks.";
+    }
+
+    // Create session before the call so the webhook URL is ready
+    const session = voiceSessionManager.create({
+      callSid: null, // updated after Twilio responds
+      greeting: opts.greeting || null,
+    });
+
+    // Store voice model preference on session for TaskRunner to pick up
+    // Voice uses the fastest model by default (VOICE_MODEL env var or haiku/flash)
+    session.preferredModel = opts.model || process.env.VOICE_MODEL || null;
+
+    const body = {
+      To:             to,
+      From:           from,
+      Url:            `${webhookBase}/voice/answer/${session.id}`,
+      StatusCallback: `${webhookBase}/voice/status/${session.id}`,
+      StatusCallbackMethod: "POST",
+      Method: "POST",
+    };
+    if (opts.timeout) body.Timeout = String(opts.timeout);
+    if (opts.record === true) body.Record = "true";
+    if (opts.machineDetection) body.MachineDetection = opts.machineDetection;
+
+    console.log(`[makeVoiceCall] Initiating interactive call to ${to} from ${from} | session ${session.id}`);
+    const result = await _twilioRequest(accountSid, authToken, "POST", "/Calls.json", body);
+
+    if (!result.ok) {
+      voiceSessionManager.delete(session.id);
+      return `Failed to initiate call: ${result.data?.message || result.data?.code || result.status}`;
+    }
+
+    // Update session with real callSid from Twilio
+    session.callSid = result.data.sid;
+
+    const d = result.data;
+    return (
+      `Interactive call started.\n` +
+      `Session ID: ${session.id}  ← use this for listen/speak/end\n` +
+      `Call SID:   ${d.sid}\n` +
+      `Status:     ${d.status} (will update to "in-progress" when answered)\n` +
+      `To:         ${d.to} | From: ${d.from}\n\n` +
+      `Next step: call makeVoiceCall("listen", "${session.id}") to wait for the caller to speak.`
+    );
+  }
+
+  // ── call — one-shot call that speaks a message and hangs up ─────────────────
+  if (action === "call") {
+    const to = phoneNumberOrSessionId;
+    if (!to) return "Error: phoneNumber is required for call.";
+    const from = opts.from || fromNumber;
+    if (!from) return 'Error: No outbound number. Set TWILIO_PHONE_FROM in .env or pass optionsJson {"from":"+1555..."}';
+
+    const body = { To: to, From: from };
+
+    if (opts.url) {
+      body.Url = opts.url;
+    } else if (opts.message) {
+      body.Twiml = _buildSayTwiML(opts.message, opts.voice || "Polly.Joanna", opts.language || "en-US");
+    } else {
+      return 'Error: Provide optionsJson {"message":"Hello"} to speak a message, or {"url":"https://twiml-url"} for custom TwiML.';
+    }
+
+    if (opts.statusCallback) body.StatusCallback = opts.statusCallback;
+    if (opts.timeout) body.Timeout = String(opts.timeout);
+    if (opts.record === true) body.Record = "true";
+
+    console.log(`[makeVoiceCall] One-shot call to ${to} from ${from}`);
+    const result = await _twilioRequest(accountSid, authToken, "POST", "/Calls.json", body);
+
+    if (!result.ok) {
+      return `Failed to initiate call: ${result.data?.message || result.data?.code || result.status}`;
+    }
+
+    const d = result.data;
+    return `Call initiated. SID: ${d.sid} | Status: ${d.status} | To: ${d.to} | From: ${d.from}`;
+  }
+
+  // ── hangup — end a call by SID (non-session, admin use) ─────────────────────
+  if (action === "hangup") {
+    const sid = opts.sid || phoneNumberOrSessionId;
+    if (!sid) return 'Error: Provide call SID via optionsJson {"sid":"CA..."} or as the second argument.';
+
+    const result = await _twilioRequest(accountSid, authToken, "POST", `/Calls/${sid}.json`, { Status: "completed" });
+    if (!result.ok) return `Failed to hang up: ${result.data?.message || result.status}`;
+    return `Call ${result.data.sid} ended. Final status: ${result.data.status}`;
+  }
+
+  // ── list — recent calls ──────────────────────────────────────────────────────
+  if (action === "list") {
+    const limit = opts.limit || 20;
+    const statusFilter = opts.status ? `&Status=${opts.status}` : "";
+    const toFilter = opts.to ? `&To=${encodeURIComponent(opts.to)}` : "";
+
+    const result = await _twilioRequest(
+      accountSid, authToken, "GET",
+      `/Calls.json?PageSize=${limit}${statusFilter}${toFilter}`
+    );
+
+    if (!result.ok) return `Failed to list calls: ${result.data?.message || result.status}`;
+
+    const calls = result.data?.calls || [];
+    if (calls.length === 0) return "No calls found.";
+
+    const lines = calls.map((c) => {
+      const dur = c.duration ? ` (${c.duration}s)` : "";
+      return `  ${c.sid} | ${c.status.padEnd(12)} | ${c.to} ← ${c.from}${dur} | ${c.start_time || c.date_created}`;
+    });
+    return `Recent calls (${calls.length}):\n${lines.join("\n")}`;
+  }
+
+  return `Error: Unknown action "${action}". Supported: initiate, listen, speak, end, status, call, hangup, list.`;
+}
+
+export const makeVoiceCallDescription =
+  'makeVoiceCall(action: string, phoneNumberOrSessionId?: string, optionsJson?: string) - Outbound voice calls via Twilio.\n' +
+  'INTERACTIVE MODE (two-way conversation):\n' +
+  '  action=initiate: start a call. optionsJson: {"greeting":"Hi, how can I help?","from":"+1555..."}. Returns sessionId.\n' +
+  '  action=listen:   wait for caller to speak. First arg = sessionId. Returns: "Caller said: \\"...\\""\n' +
+  '  action=speak:    say something to caller. First arg = sessionId. optionsJson: {"message":"Got it, one moment..."}\n' +
+  '  action=end:      hang up the call. First arg = sessionId.\n' +
+  '  action=status:   show session state and transcript. First arg = sessionId.\n' +
+  'ONE-SHOT MODE:\n' +
+  '  action=call:     dial a number and speak a message. optionsJson: {"message":"Your order is ready"} or {"url":"https://twiml-url"}\n' +
+  '  action=hangup:   end a call by SID. optionsJson: {"sid":"CA..."}\n' +
+  '  action=list:     recent calls. optionsJson: {"limit":20,"status":"completed","to":"+1555..."}\n' +
+  'Credentials: TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN + TWILIO_PHONE_FROM in .env. Interactive mode also needs VOICE_WEBHOOK_BASE_URL.';

package/src/tools/manageAgents.js

@@ -1,5 +1,5 @@
 /**
- * manageAgents(action, paramsJson?) — List, kill, or steer running sub-agents.
+ * manageAgents(action, paramsJson?) - List, kill, or steer running sub-agents.
  * Inspired by OpenClaw's subagents tool.
  */
 import {
@@ -17,7 +17,7 @@ export function manageAgents(action, paramsJson) {
         const agents = listActiveAgents();
         if (agents.length === 0) return "No active sub-agents running.";
         const lines = agents.map(
-          (a) => `• ${a.id} — "${a.task}" (running ${Math.round(a.elapsedMs / 1000)}s)`
+          (a) => `• ${a.id} - "${a.task}" (running ${Math.round(a.elapsedMs / 1000)}s)`
         );
         return `Active sub-agents (${agents.length}):\n${lines.join("\n")}`;
       }