whatsapp-pi 1.0.62 → 1.0.64

package/README.md

@@ -19,7 +19,6 @@ Pi is a powerful agentic AI coding assistant that operates in your terminal. Thi
   - Manage aliases and print allowed contacts from the menu
 - **Allowed Groups**: Control which WhatsApp groups can interact with Pi
   - Add group JIDs with optional aliases
-  - Choose reaction mode per group: **Active** (reply to all allowed group messages) or **Passive** (reply only when mentioned with @)
   - Only groups in Allowed Groups are processed by the agent
 - **Recents & History**: Browse recent conversations, inspect full message history, and reply from message detail view
 - **Reliable Messaging**: Queue-based message sending with retry logic
@@ -127,6 +126,20 @@ pi -e whatsapp-pi.ts --whatsapp-pi-online
 - **Send Message** and `send_wa_message` are outbound only.
 - If you message yourself, WhatsApp may show sent/read ticks, but that does not guarantee Pi will treat it as a trigger.
 
+## LLM-Callable Tools
+
+The extension registers the following tools that the Pi agent can call:
+
+| Tool | Direction | Description |
+| --- | --- | --- |
+| `send_wa_message` | outbound | Send a WhatsApp message to a contact or group (or reply to the last conversation if `jid` is omitted). |
+| `send_reaction` | outbound | React to a WhatsApp message with an emoji. |
+| `list_wa_conversations` | read-only | List recent conversations from the local recents store. Supports `onlyIncoming`, `onlyAllowed`, and `limit`. |
+| `get_wa_conversation_history` | read-only | Get the most recent messages with a given `senderNumber` (accepts `+E164`, raw digits, or a JID). Supports `limit`. |
+| `check_wa_new_messages` | read-only | List conversations whose most recent message is incoming (i.e. waiting for a reply). Supports `sinceTimestamp` (ms epoch). |
+
+The three read-only tools query the local recents store at `~/.pi/whatsapp-pi/recents/recents.json`. They never touch the network and do not mark messages as read.
+
 ## WhatsApp Numbers and JIDs
 
 - Contacts use phone format in UI: `+5511999999999`
@@ -153,8 +166,8 @@ pi -e whatsapp-pi.ts --whatsapp-pi-online
 
 ### Allowed Groups Management
 - **Add Group** - Add a WhatsApp group JID to the allowed groups list (format: 120363012345@g.us)
-- **Select a group** - Open a submenu with **History**, **Send Message**, **Print Group JID**, **Reaction Mode**, **Add Alias**, **Remove Alias**, **Remove Group**, and **Back**
-- **Reaction Mode** - Switch between **Active** and **Passive** behavior for that group
+- **Select a group** - Open a submenu with **History**, **Send Message**, **Print Group JID**, **Add Alias**, **Remove Alias**, **Remove Group**, and **Back**
+
 - **Back** - Return to main menu
 
 ### Recents Management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-pi",
-  "version": "1.0.62",
+  "version": "1.0.64",
   "type": "module",
   "description": "WhatsApp integration extension for Pi",
   "main": "whatsapp-pi.ts",

package/src/i18n.ts

@@ -194,6 +194,14 @@ const fallback = {
     "tool.sendReaction.label": "Send WhatsApp Reaction",
     "tool.sendReaction.description": "React to a WhatsApp message with an emoji",
     "tool.sendReaction.error.invalidEmoji": "Invalid emoji provided",
+    "tool.listConversations.label": "List WhatsApp Conversations",
+    "tool.listConversations.description": "List recent WhatsApp conversations from the local recents store (sender number, optional name, last message preview, direction, timestamp, allowed flag). Read-only.",
+    "tool.getHistory.label": "Get WhatsApp Conversation History",
+    "tool.getHistory.description": "Get the most recent messages exchanged with a given WhatsApp sender from the local recents store. Accepts a phone number (+E164 or raw digits) or a JID. Read-only.",
+    "tool.checkNew.label": "Check WhatsApp New Messages",
+    "tool.checkNew.description": "List recent WhatsApp conversations whose most recent message is incoming (i.e. waiting for a reply). Optionally filter by a `sinceTimestamp` (ms epoch). Read-only.",
+    "tool.error.notInitialized": "WhatsApp-Pi recents store not initialized",
+    "tool.error.missingSender": "senderNumber is required",
     "incoming.media.audioTranscribing": "[WhatsApp-Pi] Transcribing audio from {pushName}...",
     "incoming.media.audioTranscribed": "[Transcribed Audio]: {transcription}",
     "incoming.media.imageDownloading": "[WhatsApp-Pi] Downloading image from {pushName}...",

package/whatsapp-pi.ts

@@ -401,6 +401,112 @@ export default function (pi: ExtensionAPI) {
         }
     });
 
+    // Register list_wa_conversations tool (LLM-callable, read-only)
+    pi.registerTool({
+        name: "list_wa_conversations",
+        label: t("tool.listConversations.label"),
+        description: t("tool.listConversations.description"),
+        promptSnippet: "list_wa_conversations({onlyIncoming?, onlyAllowed?, limit?}) - List recent WhatsApp conversations from the local recents store. Read-only; safe to call any time.",
+        parameters: Type.Object({
+            onlyIncoming: Type.Optional(Type.Boolean({ description: "Only return conversations whose last message is incoming (waiting for a reply)." })),
+            onlyAllowed: Type.Optional(Type.Boolean({ description: "Only return conversations from senders/groups currently in the allow list." })),
+            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Maximum number of conversations to return (default 20)." }))
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const conversations = await recentsService.getRecentConversations();
+                let filtered = conversations;
+                if (params.onlyIncoming) {
+                    filtered = filtered.filter(c => c.lastMessageDirection === 'incoming');
+                }
+                if (params.onlyAllowed) {
+                    filtered = filtered.filter(c => c.isAllowed);
+                }
+                const limit = typeof params.limit === 'number' ? params.limit : 20;
+                filtered = filtered.slice(0, limit);
+                return {
+                    isError: false,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: true, count: filtered.length, conversations: filtered }) }]
+                };
+            } catch (error) {
+                return {
+                    isError: true,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }) }]
+                };
+            }
+        }
+    });
+
+    // Register get_wa_conversation_history tool (LLM-callable, read-only)
+    pi.registerTool({
+        name: "get_wa_conversation_history",
+        label: t("tool.getHistory.label"),
+        description: t("tool.getHistory.description"),
+        promptSnippet: "get_wa_conversation_history({senderNumber, limit?}) - Get the most recent messages with a sender. `senderNumber` accepts +E164 (e.g. +14155551212), raw digits, or a JID (e.g. 14155551212@s.whatsapp.net, 120363012345@g.us). Read-only.",
+        parameters: Type.Object({
+            senderNumber: Type.String({ description: "Phone number (+E164 or raw digits) or WhatsApp JID of the conversation." }),
+            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Maximum number of messages to return (default 20)." }))
+        }),
+        async execute(_toolCallId, params) {
+            if (!params.senderNumber || !params.senderNumber.trim()) {
+                return {
+                    isError: true,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: t("tool.error.missingSender") }) }]
+                };
+            }
+            try {
+                const messages = await recentsService.getConversationHistory(params.senderNumber);
+                const limit = typeof params.limit === 'number' ? params.limit : 20;
+                const sliced = messages.slice(-limit);
+                return {
+                    isError: false,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: true, count: sliced.length, messages: sliced }) }]
+                };
+            } catch (error) {
+                return {
+                    isError: true,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }) }]
+                };
+            }
+        }
+    });
+
+    // Register check_wa_new_messages tool (LLM-callable, read-only)
+    pi.registerTool({
+        name: "check_wa_new_messages",
+        label: t("tool.checkNew.label"),
+        description: t("tool.checkNew.description"),
+        promptSnippet: "check_wa_new_messages({sinceTimestamp?}) - List conversations whose most recent message is incoming (i.e. waiting for a reply). Optional `sinceTimestamp` (ms epoch) filters to messages newer than that. Read-only.",
+        parameters: Type.Object({
+            sinceTimestamp: Type.Optional(Type.Integer({ minimum: 0, description: "Only include conversations whose last incoming message timestamp is strictly greater than this (ms since epoch)." }))
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const conversations = await recentsService.getRecentConversations();
+                const since = typeof params.sinceTimestamp === 'number' ? params.sinceTimestamp : 0;
+                const pending = conversations.filter(c =>
+                    c.lastMessageDirection === 'incoming' && c.lastMessageTime > since
+                );
+                return {
+                    isError: false,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: true, count: pending.length, conversations: pending }) }]
+                };
+            } catch (error) {
+                return {
+                    isError: true,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }) }]
+                };
+            }
+        }
+    });
+
     // Suppress automatic message_end reply when tool already sent
     // This is checked by the message_end handler below