whatsapp-group-summary 1.0.0

package/README.md

@@ -0,0 +1,395 @@
+# 🤖 WhatsApp Group Summary Bot
+
+![Logo](logo.jpg)
+
+> Bot ringkasan grup WhatsApp untuk **Hermes Agent** — merekam **semua** chat anggota grup secara diam-diam dan mengirim ringkasan terstruktur **2x sehari** (07:00 & 23:00 WIB) dengan bahasa Indonesia santai.
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Hermes-Agent-6C5CE7?style=flat-square" alt="Hermes Agent">
+  <img src="https://img.shields.io/badge/Platform-WhatsApp-25D366?style=flat-square&logo=whatsapp" alt="WhatsApp">
+  <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License">
+  <img src="https://img.shields.io/badge/Language-ID-santai-orange?style=flat-square" alt="Bahasa Indonesia">
+</p>
+
+---
+
+## ✨ Fitur
+
+| Fitur | Deskripsi |
+|-------|-----------|
+| 📝 **Rekam Semua Chat** | Seluruh pesan dari **semua** anggota grup direkam ke JSONL — bukan cuma user whitelist |
+| 🤫 **Silent Recording** | Bot tidak merespon chat biasa. Hanya aktif saat di-@mention atau ada perintah `/` |
+| 📊 **Summary 2x Sehari** | Pagi (07:00 WIB) & malam (23:00 WIB) — format terstruktur, padat, informatif |
+| 🔥 **Mode Roast** | Opsional — versi sarkas & lucu dari ringkasan buat suasana grup lebih hidup |
+| 🇮🇩 **Casual Indonesian** | Gaya bahasa santai (gw/lo), bukan formal — cocok buat grup pertemanan |
+| 🔗 **Auto-detect Links** | Semua URL yang di-share otomatis tercantum di section Link-link |
+| 📋 **Action Tracking** | Follow-up items & pertanyaan terbuka dicatat biar ga ada yang kelewat |
+
+---
+
+## 📊 Contoh Output
+
+### Mode Normal
+```
+*Summary General — 12 jam terakhir*
+- *Inti Diskusi*
+- Ngobrolin tools AI: GPT 5.6 Sol, Codex, Claude vs ChatGPT 5 buat slicing UI
+- Sharing repo token saver: oh-my-pi dari Nado dan paleo dari mmoaa
+- Diskusi akses remote: Tailscale vs NetBird
+- Info event Lovable + temp mail smailpro buat klaim kredit
+- *Keputusan*
+- Tidak ada keputusan formal.
+- *Follow-up / Action*
+- Pen?: cek detail deploy error
+- Yanda Nooryuda: cek member/top hari ini
+- mmoaa: minta stars buat repo paleo
+- *Pertanyaan Terbuka*
+- API Gmaps berbayar atau gratis?
+- Sol udah masuk Codex official belum?
+- Mending Tailscale atau NetBird buat remote?
+- *Link-link*
+- Nado: oh-my-pi token saver — github.com/Fernado03/oh-my-pi-supreme-token-saver
+- mmoaa: paleo token saver — github.com/mocasus/paleo
+- 你算哪块小饼干？: bluk-cf auto CF — github.com/iAm-182/bluk-cf
+```
+
+### Mode Roast 🔥
+```
+*Summary Roast — 12 jam terakhir 🔥*
+- *Yang Paling Nyablak*
+- DickySusanto gas terus nanya Sol mulu, udah kayak sales GPT
+- Pen? classic — deploy error done tapi ga dicek
+- *Drama & Perdebatan*
+- Tailscale vs NetBird debat ga kelar-kelar, pada mau jadi superhero remote akses
+- *Receh Tapi Menghibur*
+- Azhar share link invite grup ke-15 kali ini
+- *Keputusan (yg akhirnya diambil setelah debat panjang)*
+- Ga ada. Seperti biasa.
+- *PR Yang Belum Kelar*
+- Pen?: deploy error masih menggantung
+- Yanda: member check masih waiting
+- *Pertanyaan Nyangkut*
+- Gmaps bayar apa gratis? udah 3 hari ini pertanyaan yg sama
+- *Link Berserakan*
+- Nado: token saver — github.com/Fernado03/oh-my-pi-supreme-token-saver
+```
+
+---
+
+## 🏗️ Arsitektur
+
+```
+┌─────────────────────────────────────────────────┐
+│                 WhatsApp Group                    │
+│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐            │
+│  │User1│  │User2│  │User3│  │UserN│  ...         │
+│  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘            │
+└─────┼────────┼────────┼────────┼────────────────┘
+      │        │        │        │
+      ▼        ▼        ▼        ▼
+┌─────────────────────────────────────┐
+│        Baileys Bridge (Node.js)     │
+│  bridge.js — !isGroup skip allowlist│  ◄── Patch A
+└────────────────┬────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────┐
+│      Python Adapter (Hermes)         │
+│  whatsapp_common.py — no allowlist   │  ◄── Patch B
+│  adapter.py — _record_group_msg()   │  ◄── Patch C
+└────────┬───────────────────┬────────┘
+         │                   │
+         ▼                   ▼
+┌─────────────────┐  ┌──────────────────┐
+│  JSONL Logs      │  │  Agent Response  │
+│  group_logs/     │  │  (only @mention) │
+│  <id>.jsonl      │  │                  │
+└────────┬─────────┘  └──────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────┐
+│         Cron Jobs (2x daily)         │
+│  07:00 WIB — Morning Summary        │
+│  23:00 WIB — Evening Summary        │
+└────────────────┬────────────────────┘
+                 │
+                 ▼
+         ┌──────────────┐
+         │ WhatsApp Group │
+         │  (clean output)│
+         └──────────────┘
+```
+
+---
+
+## 📦 Instalasi
+
+### Prasyarat
+
+- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** terinstall & WhatsApp gateway berjalan
+- **Akses terminal/SSH** ke server Hermes
+- **Hermes sudah di-invite** ke grup WhatsApp target
+- `git`, `curl`, `python3` tersedia
+
+---
+
+### Step 1: Install Skill
+
+```bash
+# Via npx (recommended)
+npx github:mocasus/whatsapp-group-summary
+
+# Atau via hermes skills install
+hermes skills install https://raw.githubusercontent.com/mocasus/whatsapp-group-summary/main/SKILL.md
+
+# Atau manual git clone
+git clone https://github.com/mocasus/whatsapp-group-summary.git ~/.hermes/skills/whatsapp-group-summary-bot
+```
+
+---
+
+### Step 2: Patch Source Files
+
+> ⚠️ **PENTING:** Patch akan **hilang setiap `hermes update`**. Simpan repo ini dan re-apply setelah update. Gunakan skill `whatsapp-group-summary-bot` untuk auto-detect dan re-apply.
+
+#### Patch A — Bridge (`bridge.js`)
+
+**File:** `~/.hermes/hermes-agent/scripts/whatsapp-bridge/bridge.js`  
+**Line:** ~637
+
+```diff
+- if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
++ if (!isGroup && WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+```
+
+**Efek:** Bridge meneruskan pesan dari **semua** anggota grup, bukan cuma user whitelist.
+
+---
+
+#### Patch B — Adapter Logic (`whatsapp_common.py`)
+
+**File:** `~/.hermes/hermes-agent/gateway/platforms/whatsapp_common.py`  
+**Line:** ~361-365
+
+```diff
+-            # Only respond to whitelisted senders in groups
+-            if self._allow_from:
+-                sender_id = str(data.get("senderId") or ...)
+-                if sender_id and not self._matches_whatsapp_allowlist(...):
+-                    return False
++            # NOTE: patched — allowlist check skipped for groups.
++            # Only DMs are gated by WHATSAPP_ALLOWED_USERS.
+```
+
+**Efek:** Python adapter tidak memfilter pesan grup berdasarkan whitelist.
+
+---
+
+#### Patch C — Silent Recorder (`adapter.py`)
+
+**File:** `~/.hermes/hermes-agent/plugins/platforms/whatsapp/adapter.py`
+
+**Tambahkan method** sebelum `_build_message_event` (~line 1341):
+
+```python
+def _record_group_message_sync(self, data):
+    """Record all group messages to JSONL for cron summary (non-blocking)."""
+    try:
+        import json, os
+        chat_id = str(data.get("chatId") or "")
+        if not chat_id.endswith("@g.us"):
+            return
+        body = str(data.get("body") or "").strip()
+        if not body:
+            return
+        log_dir = os.path.expanduser("~/.hermes/platforms/whatsapp/group_logs")
+        os.makedirs(log_dir, exist_ok=True)
+        log_file = os.path.join(log_dir, f"{chat_id}.jsonl")
+        entry = {
+            "ts": data.get("timestamp", 0),
+            "sender": str(data.get("senderName") or data.get("senderId") or ""),
+            "body": body,
+        }
+        with open(log_file, "a") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except Exception:
+        pass  # never block message processing on logging failure
+```
+
+**Tambahkan di `_build_message_event`**, sebelum `if not self._should_process_message(data):`
+
+```python
+# PATCHED: Record all group messages for cron summary
+if data.get("isGroup", False):
+    self._record_group_message_sync(data)
+```
+
+**Efek:** Setiap pesan grup ditulis ke file JSONL tanpa mengganggu processing normal.
+
+---
+
+### Step 3: Environment Variable
+
+Tambahkan ke environment config Hermes:
+
+```bash
+# Require @mention for bot response in groups (messages still recorded)
+WHATSAPP_REQUIRE_MENTION=true
+```
+
+---
+
+### Step 4: Restart Gateway
+
+```bash
+hermes gateway restart
+```
+
+> 💡 Jika restart dari dalam gateway diblokir, jalankan dari **terminal SSH terpisah**.
+
+---
+
+### Step 5: Verifikasi
+
+Kirim **satu pesan test** di grup WhatsApp mana pun, lalu:
+
+```bash
+# Cek file log per grup
+ls -la ~/.hermes/platforms/whatsapp/group_logs/
+
+# Lihat isi log (ganti <chat_id> dgn ID grup)
+cat ~/.hermes/platforms/whatsapp/group_logs/<chat_id>@g.us.jsonl | tail -5
+```
+
+Harusnya muncul pesan test tadi dengan format JSON:
+```json
+{"ts": 1783736100, "sender": "Nama Kamu", "body": "test"}
+```
+
+---
+
+### Step 6: Setup Cron Jobs
+
+#### 6a. Dapatkan Group ID
+
+Tag Hermes di grup target: **"apa id grup ini?"**  
+Hermes akan membalas dengan format `` `123456789@g.us` ``
+
+#### 6b. Buat Cron Jobs via Hermes
+
+```
+Morning: schedule = 0 0 * * *  (07:00 WIB)
+Evening: schedule = 0 16 * * * (23:00 WIB)
+Deliver: whatsapp:<chat_id>@g.us
+```
+
+**Prompt Normal:**
+```
+Kamu adalah bot ringkasan. HANYA OUTPUT RINGKASAN. Baca ~/.hermes/platforms/whatsapp/group_logs/<CHAT_ID>.jsonl, filter 12 jam (ts=UNIX timestamp). TANPA blank line:
+
+*Summary General — 12 jam terakhir*
+- *Inti Diskusi*
+- [rangkum per topik, gabungin chat mirip]
+- *Keputusan*
+- [keputusan atau "Tidak ada keputusan formal."]
+- *Follow-up / Action*
+- [Nama]: [action]
+- *Pertanyaan Terbuka*
+- [pertanyaan]
+- *Link-link*
+- [Nama]: [desc] — [URL]
+
+ATURAN: No metadata, no blank line, no job info. HANYA ringkasan. Nama dari field "sender". Bahasa Indonesia santai.
+```
+
+---
+
+## 🔥 Mode Roast
+
+Untuk mengaktifkan versi sarkas/lucu, update prompt cron job dengan:
+
+```
+Kamu adalah bot ringkasan versi ROAST. Gaya: sarkas, lucu, roasting anggota grup tapi tetap friendly — kayak temen yg galak tapi sayang.
+
+*Summary Roast — 12 jam terakhir 🔥*
+- *Yang Paling Nyablak*
+- [siapa paling rame + roast ringan]
+- *Drama & Perdebatan*
+- [topik panas + komentar sarkas]
+- *Receh Tapi Menghibur*
+- [chat random lucu/absurd]
+- *Keputusan (yg akhirnya diambil setelah debat panjang)*
+- [keputusan]
+- *PR Yang Belum Kelar*
+- [Nama]: [action + roast]
+- *Pertanyaan Nyangkut*
+- [pertanyaan + "ada yg bisa jawab ga nih?"]
+- *Link Berserakan*
+- [Nama]: [desc] — [URL]
+
+ATURAN: Roast friendly, bukan bully. No metadata, no blank line.
+```
+
+Toggle via Hermes: **"ubah <nama_grup> ke mode roast"** / **"balikin <nama_grup> ke normal"**
+
+---
+
+## 📁 Struktur Repo
+
+```
+whatsapp-group-summary/
+├── README.md                              ← Kamu di sini
+├── logo.jpg                               ← Logo bot
+├── SKILL.md                               ← Skill utama (Hermes format)
+└── references/
+    ├── bridge-api.md                      ← WhatsApp bridge API reference
+    ├── record-all-group-messages.md       ← Recording architecture detail
+    ├── user-format-reference.md           ← Format referensi dari user
+    ├── verify-recording.md                ← Langkah verifikasi recording
+    ├── whatsapp-bridge-limitations.md     ← Batasan bridge WhatsApp
+    └── whatsapp-group-ids.md              ← Daftar ID grup yang di-manage
+```
+
+---
+
+## 🛠️ Troubleshooting
+
+| Gejala | Penyebab | Solusi |
+|--------|----------|--------|
+| `group_logs/` kosong | Patch A/B/C belum applied | Re-apply patch, restart gateway |
+| Recording jalan tapi bot tetep respon | `WHATSAPP_REQUIRE_MENTION` belum di-set | Pastikan ada di `.env`, restart gateway |
+| Cron output ada `Cronjob Response:...` | Normal — hanya muncul di DM delivery | Delivery ke grup WhatsApp langsung clean |
+| Patch hilang setelah `hermes update` | Update menimpa source | Re-apply patch A/B/C setiap update |
+| `gateway restart` diblokir | Berjalan dari dalam session Hermes | Restart dari terminal SSH terpisah |
+| Blank lines di output summary | Prompt kurang "TANPA blank line" | Update prompt — tambahkan constraint |
+| Bridge ga kirim pesan grup | `WHATSAPP_GROUP_POLICY` bukan `open` | Set `WHATSAPP_GROUP_POLICY=open` di `.env` |
+
+---
+
+## ⚡ Quick Re-Apply After Update
+
+Setelah `hermes update`, jalankan:
+
+```bash
+# Re-apply semua patch dari repo
+cd ~/.hermes/skills/whatsapp-group-summary-bot
+# Patch A: bridge.js
+sed -i 's/if (WHATSAPP_DM_POLICY/if (!isGroup \&\& WHATSAPP_DM_POLICY/' \
+  ~/.hermes/hermes-agent/scripts/whatsapp-bridge/bridge.js
+# Restart gateway
+hermes gateway restart
+```
+
+> Patch B & C perlu di-apply manual karena lebih kompleks. Cek `SKILL.md` untuk detail.
+
+---
+
+## 📝 License
+
+MIT © [mocasus](https://github.com/mocasus)
+
+---
+
+<p align="center">
+  <sub>Dibuat dengan ☕ dan sedikit roasting 🔥</sub>
+</p>

package/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: whatsapp-group-summary-bot
+description: Setup WhatsApp group summary bot — records all messages silently via patched bridge+adapter, reads from JSONL logs, sends structured twice-daily summaries (07:00 & 23:00 WIB) in clean WhatsApp-friendly format (no metadata, no blank lines, casual Indonesian).
+triggers:
+  - User wants auto-summary or "ringkasan" for WhatsApp group
+  - User shares WhatsApp group invite link with summary request
+  - User says "set summary" or "summary bot" in group/DM
+---
+
+# WhatsApp Group Summary Bot
+
+Two parts: **(A) message recording** via patched bridge/adapter → JSONL, **(B) cron jobs** that read JSONL and deliver summaries.
+
+⚠️ **Core patches required.** WhatsApp normally only forwards @mentioned or whitelisted-user messages. Three source files must be patched to record ALL messages silently. Patches WILL be overwritten on `hermes update` — re-apply after updates.
+
+---
+
+## Part A: Message Recording (One-Time Setup)
+
+### A1. Bridge — `bridge.js`
+
+Patch: `Hermes `scripts/whatsapp-bridge/bridge.js`` ~line 637
+
+**Before:**
+```js
+if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+```
+**After (add `!isGroup &&`):**
+```js
+if (!isGroup && WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+```
+
+### A2. Adapter Logic — `whatsapp_common.py`
+
+Patch: `~/.hermes/hermes-agent/gateway/platforms/whatsapp_common.py` ~lines 361-365
+
+Remove the group allowlist check — replace with comment noting the patch.
+
+### A3. Silent Recorder — `adapter.py`
+
+Patch: `~/.hermes/hermes-agent/plugins/platforms/whatsapp/adapter.py`
+
+Add method before `_build_message_event`:
+```python
+def _record_group_message_sync(self, data):
+    try:
+        import json, os
+        chat_id = str(data.get("chatId") or "")
+        if not chat_id.endswith("@g.us"): return
+        body = str(data.get("body") or "").strip()
+        if not body: return
+        log_dir = os.path.expanduser("~/.hermes/platforms/whatsapp/group_logs")
+        os.makedirs(log_dir, exist_ok=True)
+        entry = {"ts": data.get("timestamp", 0), "sender": str(data.get("senderName") or data.get("senderId") or ""), "body": body}
+        with open(os.path.join(log_dir, f"{chat_id}.jsonl"), "a") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except Exception: pass
+```
+
+In `_build_message_event`, before `_should_process_message` check:
+```python
+if data.get("isGroup", False):
+    self._record_group_message_sync(data)
+```
+
+### A4. Env
+
+Add to the Hermes environment config file:
+
+### A5. Restart
+
+`hermes gateway restart` from **external terminal** (cannot restart from inside gateway).
+
+**Verify:** send test message in any group → `ls ~/.hermes/platforms/whatsapp/group_logs/` should show `<chat_id>.jsonl` with your message.
+See `references/verify-recording.md` for full checklist.
+
+### A6. Reference Files
+
+- `references/bridge-api.md` — bridge HTTP API: group name lookup, recording status
+- `references/verify-recording.md` — step-by-step verification after patch + restart
+
+---
+
+## Part B: Cron Jobs
+
+### B1. Get Group Info
+
+- **Invite link**: `curl -sL "URL" | grep -oP '(?<=og:title" content=")[^"]+'`
+- **Group ID**: tag Hermes in group with "apa id grup ini?" — answer `\`<id>@g.us\``, nothing else
+- **User MUST add Hermes to group manually** — invite links don't work for bots
+
+### B2. Create Jobs
+
+| Job | Cron (UTC) | WIB |
+|-----|-----------|-----|
+| Morning | `0 0 * * *` | 07:00 |
+| Evening | `0 16 * * *` | 23:00 |
+
+Deliver to `whatsapp:<chat_id>@g.us` **immediately** — never use `origin` as placeholder.
+
+### B3. Cron Prompt
+
+**Normal mode (default):**
+```
+Kamu adalah bot ringkasan. HANYA OUTPUT RINGKASAN. Baca ~/.hermes/platforms/whatsapp/group_logs/<CHAT_ID>.jsonl, filter 12 jam (ts=UNIX timestamp integer). TANPA blank line:
+
+*Summary General — 12 jam terakhir*
+- *Inti Diskusi*
+- [rangkum per topik, gabungin chat mirip]
+- *Keputusan*
+- [keputusan atau "Tidak ada keputusan formal."]
+- *Follow-up / Action*
+- [Nama]: [action]
+- *Pertanyaan Terbuka*
+- [pertanyaan]
+- *Link-link*
+- [Nama]: [desc] — [URL]
+
+ATURAN: No metadata, no blank line, no job info. HANYA ringkasan. Nama dari field "sender". Bahasa Indonesia santai.
+```
+
+**Roast mode (🔥 毒舌):**
+```
+Kamu adalah bot ringkasan versi ROAST. HANYA OUTPUT RINGKASAN. Baca ~/.hermes/platforms/whatsapp/group_logs/<CHAT_ID>.jsonl, filter 12 jam. TANPA blank line. Gaya: sarkas, lucu, roasting anggota grup tapi tetap friendly, kayak temen yg galak tapi sayang.
+
+*Summary Roast — 12 jam terakhir 🔥*
+- *Yang Paling Nyablak*
+- [siapa paling rame + roasts ringan]
+- *Drama & Perdebatan*
+- [topik panas dibahas + komentar sarkas]
+- *Receh Tapi Menghibur*
+- [chat random yg lucu/absurd]
+- *Keputusan (yg akhirnya diambil setelah debat panjang)*
+- [keputusan + komentar]
+- *PR Yang Belum Kelar*
+- [Nama]: [action item + roast ringan]
+- *Pertanyaan Nyangkut*
+- [pertanyaan + "ada yg bisa jawab ga nih?"]
+- *Link Berserakan*
+- [Nama]: [desc] — [URL]
+
+ATURAN: No metadata, no blank line, no job info. Roast friendly — bukan bully. Bahasa Indonesia santai + sarkas.
+```
+
+### B4. Toggle Mode (On/Off)
+
+To switch a group's summary to roast mode:
+```
+cronjob(action='update', job_id='<job_id>', prompt='<roast prompt above>')
+```
+
+To switch back to normal:
+```
+cronjob(action='update', job_id='<job_id>', prompt='<normal prompt above>')
+```
+
+User can say: "ubah MOCA PARTY ke mode roast" or "balikin hd ke normal" — agent updates the 2 cron jobs for that group.
+
+### B5. User Style
+
+- **Casual Indonesian** — "gw", "lo", "dong", "ya", "nih", "rame bahas", "muter di", "belum jelas"
+- **Zero metadata** — no "Cronjob Response", job_id, "Catatan teknis", "To stop..."
+- **No blank lines** between sections — WhatsApp renders double newlines as ugly gaps. This is the #1 format bug the user catches. Every line in the summary MUST be a consecutive dash-prefix line with ZERO blank separators anywhere.
+- **Direct & short** — user hates verbosity ("ribet"). Never add explanatory notes, setup context, or disclaimers to the summary.
+- **Group similar chats** — merge related messages into 3-5 topic bullets under Inti Diskusi, not one bullet per message.
+- **Honest about gaps** — write "belum ada jawaban jelas" or "tidak ada solusi valid" when appropriate; never fabricate closure.
+
+### B6. Group Behavior (Anti-Ribet Rule)
+
+When tagged in a WhatsApp group with **"apa id grup ini?"** or similar bare ID request:
+- Reply with **just the ID**: `` `120363XXXXXXX@g.us` `` — no quotes, no bold, just inline code
+- Do NOT add: explanations, "mau dipake buat apa?", skill loading, setup offers, follow-up questions
+- Do NOT load this skill unless explicitly asked to "set summary"
+- Speed > conversation — user finds verbose group responses deeply frustrating ("kenapa responmu ribet?")
+
+### B7. Reference Format
+
+See [references/user-format-reference.md](references/user-format-reference.md) for the user's canonical summary example. Match the tone, grouping style, and section structure from that reference closely.
+
+---
+
+## Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Patches overwritten on `hermes update` | Re-apply A1-A3 after update |
+| Gateway restart from inside blocked | Use external SSH terminal |
+| Bridge auto-restarts, Python doesn't | Full `hermes gateway restart` needed for Python changes |
+| JSONL timestamps are UNIX epoch ints | Don't try ISO parsing; compare integer timestamps |
+| Blank lines in output | "TANPA blank line" in prompt is critical |
+| Cron delivery header `Cronjob Response: ...` | Only appears in origin/DM delivery; group delivery (`whatsapp:...`) is clean |
+| "Ribet" group responses | When tagged for "apa id grup", reply with just `` `120363XXXX@g.us` `` — no explanation, no skill loading |
+| Non-whitelisted member chat not recording | Verify 3 patches (A1-A3) applied + gateway restarted from external terminal. Bridge auto-restarts but Python adapter needs full `hermes gateway restart` |
+| Group name mismatch | Verify with `curl localhost:3000/chat/<id>@g.us` (see bridge-api.md) |
+| Summary too verbose / one bullet per message | Merge related chats into 3-5 topic bullets; group by theme, not sender |
+| Recording broken after gateway restart | Check `grep \"_build_message_event returned None\" gateway.log` — if present, Python patch not applied. Also verify `ls ~/.hermes/platforms/whatsapp/group_logs/` after sending test message |
+| Group name mislabeled | Use `curl localhost:3000/chat/<id>@g.us` to get real WhatsApp name; user often uses shortened names |
+
+---
+
+## Example Output
+
+```
+*Summary General — 12 jam terakhir*
+- *Inti Diskusi*
+- Ngobrolin tools AI: GPT 5.6 Sol, Codex, Claude vs ChatGPT 5
+- Sharing repo token saver: oh-my-pi dan paleo
+- Diskusi akses remote: Tailscale vs NetBird
+- *Keputusan*
+- Tidak ada keputusan formal.
+- *Follow-up / Action*
+- Pen?: cek detail deploy error
+- Yanda Nooryuda: cek member/top hari ini
+- *Pertanyaan Terbuka*
+- API Gmaps berbayar atau gratis?
+- Sol udah masuk Codex official?
+- *Link-link*
+- Nado: token saver — github.com/Fernado03/oh-my-pi-supreme-token-saver
+- mmoaa: paleo — github.com/mocasus/paleo
+```
+
+---
+
+## Resources
+
+- **GitHub repo:** https://github.com/mocasus/whatsapp-group-summary — standalone repo with full README + installation guide
+- **Skill location:** `~/.hermes/skills/whatsapp-group-summary-bot/SKILL.md`

package/install.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * WhatsApp Group Summary Bot — Installer
+ * 
+ * Usage: npx whatsapp-group-summary
+ * 
+ * Copies the skill to ~/.hermes/skills/whatsapp-group-summary-bot
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const SKILL_NAME = 'whatsapp-group-summary-bot';
+const HERMES_HOME = process.env.HERMES_HOME || path.join(require('os').homedir(), '.hermes');
+const TARGET_DIR = path.join(HERMES_HOME, 'skills', SKILL_NAME);
+const REPO_URL = 'https://github.com/mocasus/whatsapp-group-summary.git';
+
+console.log('🤖 WhatsApp Group Summary Bot — Installer');
+console.log(`   Target: ${TARGET_DIR}\n`);
+
+if (fs.existsSync(TARGET_DIR)) {
+  console.log('⚠️  Skill already exists. Updating...');
+  try {
+    execSync(`git -C "${TARGET_DIR}" pull`, { stdio: 'inherit' });
+    console.log('✅ Updated successfully!');
+  } catch {
+    console.log('⚠️  Git pull failed. Re-cloning...');
+    fs.rmSync(TARGET_DIR, { recursive: true, force: true });
+  }
+}
+
+if (!fs.existsSync(TARGET_DIR)) {
+  console.log('📦 Cloning skill...');
+  try {
+    execSync(`git clone "${REPO_URL}" "${TARGET_DIR}"`, { stdio: 'inherit' });
+    console.log('✅ Skill installed!');
+  } catch (e) {
+    console.error('❌ Failed to clone. Trying manual copy...');
+    fs.mkdirSync(TARGET_DIR, { recursive: true });
+    const sourceDir = path.join(__dirname, '..');
+    const files = fs.readdirSync(sourceDir);
+    for (const file of files) {
+      if (file === 'node_modules' || file === '.git' || file === 'package.json') continue;
+      const src = path.join(sourceDir, file);
+      const dest = path.join(TARGET_DIR, file);
+      fs.cpSync(src, dest, { recursive: true });
+    }
+    console.log('✅ Skill installed (manual copy)!');
+  }
+}
+
+console.log('\n📋 Next steps:');
+console.log('   1. Apply 3 source patches (see README)');
+console.log('   2. Set WHATSAPP_REQUIRE_MENTION=true in Hermes env');
+console.log('   3. Restart gateway: hermes gateway restart');
+console.log('   4. Tag @Hermes in group: "apa id grup ini?"');
+console.log('   5. Setup 2 cron jobs (morning 07:00 + evening 23:00 WIB)');
+console.log('\n   Full guide: https://github.com/mocasus/whatsapp-group-summary');

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "whatsapp-group-summary",
+  "version": "1.0.0",
+  "description": "WhatsApp group chat summary bot for Hermes Agent — record all messages silently, auto-summarize 2x daily",
+  "main": "install.js",
+  "bin": {
+    "whatsapp-group-summary": "./install.js"
+  },
+  "keywords": ["hermes-agent", "whatsapp", "summary", "group-chat", "bot"],
+  "author": "mocasus",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mocasus/whatsapp-group-summary.git"
+  }
+}

package/references/bridge-api.md

@@ -0,0 +1,27 @@
+# WhatsApp Bridge API — Quick Reference
+
+When Hermes WhatsApp gateway is running, the Baileys bridge exposes an HTTP API for querying chat/group info.
+
+## Get group name by ID
+
+Query the bridge chat endpoint with the group ID:
+```
+GET /chat/<chat_id>
+```
+
+The bridge returns JSON with `name`, `isGroup`, `participants`, and other group metadata.
+
+## Get names for all recorded groups
+
+Iterate over JSONL log files and query each group's chat endpoint to retrieve the group name.
+
+## JSONL format
+
+Each line in the log file is a JSON object:
+```json
+{"ts": 1783736100, "sender": "Display Name", "body": "message text"}
+```
+
+- `ts` = UNIX timestamp (integer, seconds)
+- `sender` = WhatsApp display name
+- `body` = message text (stickers show `"[Sticker]"`)

package/references/record-all-group-messages.md

@@ -0,0 +1,70 @@
+# Recording ALL Group Members' Messages on WhatsApp
+
+By default, Hermes WhatsApp has a **double filter** that blocks group messages from non-whitelisted users:
+
+1. **Bridge (Node.js)**: `bridge.js` line 637 — `matchesAllowedUser(senderId, ALLOWED_USERS, ...)`
+2. **Adapter (Python)**: `whatsapp_common.py` lines 361-365 — `_matches_whatsapp_allowlist(sender_id, self._allow_from)`
+
+This means only users listed in `WHATSAPP_ALLOWED_USERS` have their group messages recorded. All other members are silently dropped.
+
+## The Fix (3 changes + restart)
+
+### 1. Patch bridge.js — skip allowlist for groups
+
+**File**: Hermes `scripts/whatsapp-bridge/bridge.js`
+
+**Change line 637** from:
+```js
+if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+```
+to:
+```js
+if (!isGroup && WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+```
+
+The `!isGroup &&` prefix skips the allowlist check entirely for group messages. DMs remain gated.
+
+### 2. Patch whatsapp_common.py — remove allowlist check for groups
+
+**File**: Hermes `gateway/platforms/whatsapp_common.py`
+
+**Remove lines 361-365** (the allowlist check block):
+```python
+            # Only respond to whitelisted senders in groups (respect WHATSAPP_ALLOWED_USERS)
+            if self._allow_from:
+                sender_id = str(data.get("senderId") or data.get("from") or "")
+                if sender_id and not self._matches_whatsapp_allowlist(sender_id, self._allow_from):
+                    return False
+```
+
+Replace with a comment:
+```python
+            # NOTE: patched — allowlist check skipped for groups so all members' messages are recorded.
+            # Only DMs are gated by WHATSAPP_ALLOWED_USERS.
+```
+
+### 3. Set WHATSAPP_REQUIRE_MENTION=true
+
+In the Hermes environment configuration, add or update:
+```
+WHATSAPP_REQUIRE_MENTION=true
+```
+
+This ensures Hermes **records** all group messages but only **responds** when @mentioned. Without this, Hermes would respond to every single group message, creating chaos.
+
+### 4. Restart gateway
+
+**CRITICAL**: Cannot restart from inside the gateway. User must run from separate terminal:
+```bash
+hermes gateway restart
+```
+
+The bridge auto-restarts on kill (the adapter spawns it), but Python module changes require a full gateway restart.
+
+## Verification
+
+After restart, check recording logs at the group_logs directory configured in the adapter.
+
+## ⚠️ Warning: Patches are overwritten on `hermes update`
+
+These changes modify Hermes source code. Running `hermes update` will overwrite the patched files. Re-apply patches after each update.

package/references/user-format-reference.md

@@ -0,0 +1,41 @@
+# User's Reference Format
+
+This is the exact format the user provided as a reference for how summaries should look.
+Use this as the canonical example — match the style, tone, and structure closely.
+
+```
+*Summary General — 12 jam terakhir*
+- *Inti Diskusi*
+- Grup rame bahas perbandingan model/agent: GPT 5.6 Sol/Terra/Luna, Grok, Opus, Qwen, plus setup Codex/9router. Pen? dan DickySusanto paling dominan arahkan diskusi.
+- Banyak tanya soal akses & workflow: apakah Sol sudah masuk Codex official, beda mode sol vs sol-xhigh, serta model mana yang enak buat coding, summary, security, atau daily usage.
+- Obrolan teknis lain muter di tokenizer/LLM from scratch, rate limit 429, remote access via Tailscale/SSH/RDP, dan integrasi Agentrouter/9router.
+- Ada juga share metode/event/trial tools, tapi banyak yang sifatnya coba-coba komunitas dan belum jelas stabilitasnya.
+- *Keputusan*
+- Tidak ada keputusan formal.
+- *Follow-up / Action*
+- Pen?: sempat bilang "besok aja besok" buat lanjut share/tutor yang diminta.
+- Pen?: update singkat "deploy error done", tapi belum ada detail hasil lanjutannya.
+- Yanda Nooryuda: ada task open buat cek member/top hari ini.
+- DickySusanto / 你算哪块小饼干？: masih ada request open buat kirim benchmark kecil/model arena dan extension RF token.
+- *Pertanyaan Terbuka*
+- API Gmaps ternyata berbayar atau tidak?
+- Bagusan Tailscale atau NetBird untuk akses remote?
+- Sol sekarang bisa dipakai langsung di Codex CLI atau tetap harus lewat 9router?
+- Untuk slicing UI, lebih cocok Claude atau ChatGPT versi terbaru?
+- *Link-link*
+- Nado: share repo token saver di GitHub — github.com/Fernado03/oh-my-pi-supreme-token-saver
+- Bayu Anugerah: share extension codex-auth di Chrome Web Store.
+- Yanda Nooryuda / Azhar: share ulang link invite grup WhatsApp.
+- Mzxn Amnah: share event/community Lovable + temp mail smailpro buat klaim credit.
+- gn: share repo Vandivier/ladderly-3 terkait issue/ref lain.
+```
+
+## Key formatting rules extracted:
+
+1. **No blank lines** between sections — WhatsApp renders these as ugly gaps
+2. **Dash-prefix for everything** — `- *Section Name*` then `- content`
+3. **Group related chats into 3-5 topic bullets** under Inti Diskusi
+4. **Names**: use the WhatsApp display name, not phone number
+5. **Casual Indonesian**: "rame bahas", "muter di", "belum jelas"
+6. **Links at the bottom**: sender name, description, URL
+7. **Honest about uncertainty**: "belum ada jawaban jelas", "tidak ada solusi valid"

package/references/verify-recording.md

@@ -0,0 +1,27 @@
+# Recording Verification Checklist
+
+After applying all 3 patches and restarting the gateway:
+
+## 1. Check environment
+
+Verify `WHATSAPP_REQUIRE_MENTION` is set to `true` in the Hermes environment configuration.
+
+## 2. Verify bridge allows all group messages
+
+Check bridge is running with patched code:
+```bash
+ps aux | grep "bridge.js" | grep -v grep
+# Should show node process with --mode bot
+```
+
+## 3. Verify JSONL recording
+
+Send a test message in any group where Hermes is a member, then check the group_logs directory for a new JSONL file with your message.
+
+## 4. Verify silent recording (no agent response)
+
+Check gateway logs — regular messages should show `"_build_message_event returned None"` (not `"inbound message"`). These are silently recorded — no agent session created, no LLM cost.
+
+## 5. Verify mention still triggers agent
+
+Tag @Hermes in a group — it should create a session and respond normally. Gateway logs should show `"inbound message"` with the group chat ID.

package/references/whatsapp-bridge-limitations.md

@@ -0,0 +1,34 @@
+# WhatsApp Bridge Limitations for Group Summaries
+
+## The Problem
+
+The WhatsApp Baileys bridge (`scripts/whatsapp-bridge/bridge.js`) has a hard filter at line 637:
+
+```js
+if (WHATSAPP_DM_POLICY !== 'pairing' && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+  continue; // silently drop the message
+}
+```
+
+This runs for ALL incoming messages (`messages.upsert` handler, line 520). In bot mode (`WHATSAPP_MODE=bot`), this means group messages from non-whitelisted users are dropped at the bridge level — before they ever reach the Python gateway or the session database.
+
+## Impact on Summary Bots
+
+- **Only conversations from `WHATSAPP_ALLOWED_USERS` appear in summary output**
+- Group members not in the allowlist are invisible to the bot
+- The `WHATSAPP_GROUP_POLICY=open` setting and `WHATSAPP_REQUIRE_MENTION=false` default are irrelevant because the bridge drops messages first
+
+## Solution
+
+This skill patches the bridge to skip the allowlist check for group messages by adding `!isGroup &&` to the condition at line 637. DMs remain fully gated by the allowlist.
+
+The Python adapter (`gateway/platforms/whatsapp_common.py`) also needs a matching patch to remove its group allowlist check.
+
+## Code Locations
+
+| Component | File | Key Lines |
+|-----------|------|-----------|
+| Bridge message handler | `scripts/whatsapp-bridge/bridge.js` | 520-640 (upsert handler, allowlist check at 637) |
+| Python adapter | `plugins/platforms/whatsapp/adapter.py` | `_should_process_message` call |
+| Message processing logic | `gateway/platforms/whatsapp_common.py` | 348-385 (group policy, mention gating) |
+| Environment config | Hermes env file | `WHATSAPP_ALLOWED_USERS`, `WHATSAPP_DM_POLICY`, `WHATSAPP_REQUIRE_MENTION` |

package/references/whatsapp-group-ids.md

@@ -0,0 +1,42 @@
+# WhatsApp Group ID & Delivery Reference
+
+## Group ID Format
+
+WhatsApp group IDs always follow this pattern:
+
+```
+<digits>@g.us
+```
+
+Examples:
+- `120363273766916972@g.us` (MOCA PARTY)
+- `120363309894459310@g.us` (hd)
+- `120363307689756041@g.us` (BagiProject)
+- `120363411000649302@g.us` (unnes 1)
+
+## Getting the Group ID
+
+1. **User provides it directly** — fastest. Ask "apa ID grupnya?" in the group. Respond with JUST the ID, no explanations.
+2. **From session_search** — look for the group name in session titles when Hermes receives messages.
+3. **User tags Hermes in group** — when tagged "apa id grub ini", respond with: `ID grup ini: \`<id>@g.us\`` — keep it ONE line, no follow-up questions.
+
+## Delivery Format
+
+```
+deliver: "whatsapp:<group_id>@g.us"
+```
+
+Example: `deliver: "whatsapp:120363273766916972@g.us"`
+
+## Cron Schedule (WIB timezone)
+
+| Time (WIB) | UTC | Cron expression |
+|---|---|---|
+| 07:00 pagi | 00:00 | `0 0 * * *` |
+| 23:00 malam | 16:00 | `0 16 * * *` |
+
+WIB = UTC+7.
+
+## Batch Creation Pattern
+
+Always create both morning and evening jobs in parallel (single tool call with two `cronjob(action='create')` invocations) to save round-trips. Only ask for the group name once, then create both.