crewly 1.20.121 → 1.20.123

package/config/skills/agent/core/whatsapp-draft/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: WhatsApp Draft
+description: Write a reply draft for one of the owner's WhatsApp chats. It is saved with a short code (W12) and NEVER sent — the owner releases it by replying 「发 W12」 or from the dashboard.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - generalist
+  - operations
+  - ops
+  - support
+  - sales
+triggers:
+  - draft whatsapp reply
+  - reply on whatsapp
+  - write a whatsapp message
+tags:
+  - whatsapp
+  - draft
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# WhatsApp Draft
+
+Saves a proposed reply. **It never sends.**
+
+```bash
+bash execute.sh --chat 4915550001@s.whatsapp.net --text "Yes, 8 works — see you there"
+bash execute.sh --chat 4915550001@s.whatsapp.net --text-file /tmp/reply.txt
+bash execute.sh '{"chatId":"4915550001@s.whatsapp.net","text":"…"}'
+```
+
+## After drafting — what you must do
+
+Show the owner, in your reply to them:
+
+1. **who** it goes to (`draft.recipient`),
+2. **the exact text** (`draft.text`),
+3. **the code** (`draft.code`, e.g. `W12`),
+
+and ask them to reply **「发 W12」** to send it (or 发送 / 丢弃 on the dashboard's
+WhatsApp tab). Then stop. Only after they have replied 「发 W12」 may you run
+`whatsapp-send --draft W12`. If they change the wording, write a new draft.
+
+## Rules (owner decision — apply to every whatsapp-* skill)
+
+- **Never send anything without the owner's explicit 「发 <code>」.** One draft,
+  one confirmation, one message.
+- **Never auto-reply to anyone** — no acknowledgements, no "will get back to you".
+- **Summarise; don't paste private chats wholesale** into other channels. The
+  owner needs the gist and your proposed reply, not a transcript.
+- **Groups are low priority.** Draft for a group only when the owner asks.
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--chat` (`chatId`) | yes | Recipient chat JID; must already be in the inbox |
+| `--text` (`text`) | yes* | Reply text (max 4000 chars) |
+| `--text-file` | yes* | Read the text from a file instead |
+
+## Output
+
+```json
+{"success":true,"sent":false,
+ "draft":{"id":"…","code":"W12","recipient":"Ann","chatId":"4915550001@s.whatsapp.net","text":"Yes, 8 works — see you there"},
+ "nextStep":"NOT SENT. Show the owner: recipient Ann, the exact text above, and code W12. Ask them to reply 「发 W12」 …"}
+```
+
+## Failures
+
+`{"success":false,"reason":"chat_not_found"}` (exit 1) — you can only draft to a
+chat that is in the inbox; find it with `whatsapp-read --chats --q <name>`.

package/config/skills/agent/core/whatsapp-draft/execute.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# =============================================================================
+# whatsapp-draft — Propose a reply to a WhatsApp chat. NEVER sends.
+#
+# Backed by POST /api/whatsapp/drafts {chatId, text}. The draft gets a short
+# code (W12). Only the owner releases it: by replying 「发 W12」 in chat (then
+# whatsapp-send), or by pressing 发送 in the dashboard.
+#
+# Usage:
+#   bash execute.sh --chat <jid> --text "reply text"
+#   bash execute.sh --chat <jid> --text-file /path/to/reply.txt
+#   bash execute.sh '{"chatId":"…","text":"…"}'
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --chat <jid> --text "reply text"
+  bash execute.sh --chat <jid> --text-file /path/to/reply.txt
+  bash execute.sh '{"chatId":"…","text":"…"}'
+
+Options:
+  --chat        Recipient chat JID (must already be in the inbox)
+  --text        Reply text
+  --text-file   Read the reply text from a file
+  --help | -h   Show this help
+
+This only saves a draft. It never sends.
+EOF_USAGE
+}
+
+INPUT_JSON=""
+CHAT=""; TEXT=""; TEXT_FILE=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --chat|-c)   [ $# -ge 2 ] || error_exit "--chat requires a value";      CHAT="$2";      shift 2 ;;
+    --text)      [ $# -ge 2 ] || error_exit "--text requires a value";      TEXT="$2";      shift 2 ;;
+    --text-file) [ $# -ge 2 ] || error_exit "--text-file requires a value"; TEXT_FILE="$2"; shift 2 ;;
+    --help|-h)   print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$CHAT" ] && CHAT=$(printf '%s' "$INPUT" | jq -r '.chatId // .chat // empty')
+  [ -z "$TEXT" ] && TEXT=$(printf '%s' "$INPUT" | jq -r '.text // empty')
+fi
+
+if [ -n "$TEXT_FILE" ]; then
+  [ -f "$TEXT_FILE" ] || error_exit "text file not found: $TEXT_FILE"
+  TEXT=$(cat "$TEXT_FILE")
+fi
+
+require_param "chat (--chat)" "$CHAT"
+require_param "text (--text or --text-file)" "$TEXT"
+
+BODY=$(jq -cn --arg chatId "$CHAT" --arg text "$TEXT" '{chatId: $chatId, text: $text}')
+
+# stderr is kept apart so lib.sh's session warning cannot pollute a good response.
+ERR_FILE=$(mktemp); trap 'rm -f "$ERR_FILE"' EXIT
+RESPONSE=$(api_call POST "/whatsapp/drafts" "$BODY" 2>"$ERR_FILE") || {
+  ERR=$(tail -n 1 "$ERR_FILE")
+  printf '%s' "$ERR" | jq -c '{success: false, reason: (.details.code // .details.error // .details // .error // "unknown"), message: (.details.error // "")}' 2>/dev/null \
+    || jq -n --arg r "$ERR" '{success: false, reason: $r}'
+  exit 1
+}
+
+# The next step is the owner's, not ours: say so in the output itself.
+printf '%s' "$RESPONSE" | jq -c '.data as $d | {
+  success: true,
+  sent: false,
+  draft: {id: $d.id, code: $d.code, recipient: $d.recipient, chatId: $d.chatId, text: $d.text},
+  nextStep: ("NOT SENT. Show the owner: recipient \($d.recipient), the exact text above, and code \($d.code). Ask them to reply 「发 \($d.code)」 to send it (or use 发送/丢弃 in the dashboard). Do not call whatsapp-send until they have replied 「发 \($d.code)」.")
+}'

package/config/skills/agent/core/whatsapp-draft/execute.test.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Tests for whatsapp-draft — run with: bash execute.test.sh </dev/null
+# Spins up a python HTTP stub as the backend, asserts the request body the
+# skill sends and the JSON it prints. Exit 0 on pass.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+PORT=18843
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+class H(BaseHTTPRequestHandler):
+    def reply(self, code, body):
+        self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(body).encode())
+    def do_POST(self):
+        body = json.loads(self.rfile.read(int(self.headers.get('Content-Length', 0))) or b'{}')
+        open(LOG, 'w').write(json.dumps({'method': 'POST', 'path': self.path, 'body': body, 'agent': self.headers.get('X-Agent-Session')}))
+        if body.get('chatId') == 'unknown@s.whatsapp.net':
+            return self.reply(404, {'success': False, 'code': 'chat_not_found', 'error': 'Unknown chat: unknown@s.whatsapp.net'})
+        self.reply(201, {'success': True, 'data': {'id': 'd-1', 'code': 'W12', 'seq': 12, 'chatId': body['chatId'], 'text': body['text'],
+                                                   'status': 'pending', 'recipient': 'Ann', 'instruction': 'server says'}})
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+TMP_TEXT="$(mktemp)"
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG" "$TMP_TEXT"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+run() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null | jq -r '.error' 2>/dev/null; }
+
+OUT=$(run --chat 491@s.whatsapp.net --text 'Yes, 8 works — see you "there"')
+check "flags: path" "$(jq -r .path "$STUB_LOG")" "/api/whatsapp/drafts"
+check "flags: body" "$(jq -c .body "$STUB_LOG")" '{"chatId":"491@s.whatsapp.net","text":"Yes, 8 works — see you \"there\""}'
+check "flags: agent header" "$(jq -r .agent "$STUB_LOG")" "test-agent"
+check "output: not sent" "$(printf '%s' "$OUT" | jq -r .sent)" "false"
+check "output: draft" "$(printf '%s' "$OUT" | jq -c .draft)" '{"id":"d-1","code":"W12","recipient":"Ann","chatId":"491@s.whatsapp.net","text":"Yes, 8 works — see you \"there\""}'
+NEXT=$(printf '%s' "$OUT" | jq -r .nextStep)
+[[ "$NEXT" == *"NOT SENT"* && "$NEXT" == *"Ann"* && "$NEXT" == *"「发 W12」"* ]] && OK=yes || OK=no
+check "output: nextStep tells the agent to ask the owner for 「发 W12」" "$OK" "yes"
+
+printf 'line one\nline two' > "$TMP_TEXT"
+run --chat 491@s.whatsapp.net --text-file "$TMP_TEXT" >/dev/null
+check "text-file: body text" "$(jq -r .body.text "$STUB_LOG")" "$(printf 'line one\nline two')"
+
+run '{"chatId":"491@s.whatsapp.net","text":"json hi"}' >/dev/null
+check "json: body" "$(jq -c .body "$STUB_LOG")" '{"chatId":"491@s.whatsapp.net","text":"json hi"}'
+
+OUT=$(CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --chat unknown@s.whatsapp.net --text hi 2>/dev/null); RC=$?
+check "404: exit code" "$RC" "1"
+check "404: reason" "$(printf '%s' "$OUT" | jq -r .reason)" "chat_not_found"
+
+check "missing chat" "$(run_err --text hi)" "Missing required parameter: chat (--chat)"
+check "missing text" "$(run_err --chat 491@s.whatsapp.net)" "Missing required parameter: text (--text or --text-file)"
+check "missing text file" "$(run_err --chat x --text-file /nonexistent/file)" "text file not found: /nonexistent/file"
+check "unknown option errors" "$(run_err --send)" "Unknown option: --send"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/whatsapp-inbox/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: WhatsApp Inbox
+description: List the owner's WhatsApp chats that need a reply (last message not from the owner), with how many messages are unanswered. Read-only. 1:1 chats by default; groups are low priority.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - generalist
+  - operations
+  - ops
+  - support
+  - sales
+triggers:
+  - whatsapp inbox
+  - whatsapp messages to reply
+  - who needs a reply on whatsapp
+  - unread whatsapp
+tags:
+  - whatsapp
+  - inbox
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# WhatsApp Inbox
+
+Which of the owner's WhatsApp chats are waiting on them.
+
+```bash
+bash execute.sh                        # 1:1 chats needing a reply, newest first
+bash execute.sh --limit 50
+bash execute.sh --include-groups       # groups too (noisy, low priority)
+bash execute.sh '{"limit":20,"includeGroups":true}'
+```
+
+## Rules (owner decision — apply to every whatsapp-* skill)
+
+- **Never send anything without the owner's explicit 「发 <code>」.** You may only
+  write drafts (`whatsapp-draft`). Sending is one draft at a time, after the owner
+  replies 「发 W12」 in chat or presses 发送 in the dashboard.
+- **Never auto-reply to anyone.** Not even "got it" or "will get back to you".
+- **Summarise; don't paste private chats wholesale** into Slack, team channels,
+  the wiki, tasks, or any other place. Quote only the line you need.
+- **Groups are low priority.** Look at 1:1 chats first; only surface a group
+  when the owner is addressed directly or something is clearly urgent.
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--limit` (`limit`) | no | Max chats, default 20, max 200 |
+| `--include-groups` (`includeGroups`) | no | Include group chats (default off) |
+
+## Output
+
+```json
+{"count":1,"chats":[{"chatId":"4915550001@s.whatsapp.net","name":"Ann","isGroup":false,"unanswered":2,"lastKind":"text","lastFrom":"Ann","lastText":"at 8?","lastAt":"2026-09-24T18:02:11Z"}]}
+```
+
+`unanswered` counts messages from them since the owner last wrote in that chat.
+`lastText` is cut to 200 characters; use `whatsapp-read --chat <chatId>` for the
+conversation. `lastKind` is `text`, `image`, `document`, `audio`, `video`,
+`sticker` or `other` (media is never downloaded — you see the caption only).
+
+## Failures
+
+`{"success":false,"reason":"…"}` (exit 1). An empty list with `count: 0` just
+means nothing is waiting — or WhatsApp is not connected in inbox mode yet
+(the owner connects it under Settings → WhatsApp).

package/config/skills/agent/core/whatsapp-inbox/execute.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# =============================================================================
+# whatsapp-inbox — Which WhatsApp chats need a reply (read-only)
+#
+# Backed by GET /api/whatsapp/inbox?limit=&includeGroups=.
+# A chat "needs a reply" when its newest message is not the owner's.
+# Groups are excluded unless --include-groups is given (they are noisy).
+#
+# Usage:
+#   bash execute.sh [--limit 20] [--include-groups]
+#   bash execute.sh '{"limit":20,"includeGroups":true}'
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+# Characters of each chat's last message shown (keeps the output small).
+PREVIEW_CHARS="${CREWLY_WHATSAPP_PREVIEW_CHARS:-200}"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh [--limit 20] [--include-groups]
+  bash execute.sh '{"limit":20,"includeGroups":true}'
+
+Options:
+  --limit            Max chats (default 20, max 200)
+  --include-groups   Also list group chats (default: 1:1 chats only)
+  --help | -h        Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+LIMIT=""; INCLUDE_GROUPS=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --limit|-n)       [ $# -ge 2 ] || error_exit "--limit requires a value"; LIMIT="$2"; shift 2 ;;
+    --include-groups) INCLUDE_GROUPS=1; shift ;;
+    --help|-h)        print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$LIMIT" ] && LIMIT=$(printf '%s' "$INPUT" | jq -r '.limit // empty')
+  [ -z "$INCLUDE_GROUPS" ] && INCLUDE_GROUPS=$(printf '%s' "$INPUT" | jq -r 'if .includeGroups == true then "1" else "" end')
+fi
+
+QS=""
+[ -n "$LIMIT" ] && QS="limit=$(jq -rn --arg v "$LIMIT" '$v|@uri')"
+if [ -n "$INCLUDE_GROUPS" ]; then
+  QS="${QS:+${QS}&}includeGroups=true"
+fi
+
+# stderr is kept apart so lib.sh's session warning cannot pollute a good response.
+ERR_FILE=$(mktemp); trap 'rm -f "$ERR_FILE"' EXIT
+RESPONSE=$(api_call GET "/whatsapp/inbox${QS:+?${QS}}" 2>"$ERR_FILE") || {
+  ERR=$(tail -n 1 "$ERR_FILE")
+  printf '%s' "$ERR" | jq -c '{success: false, reason: (.details.code // .details.error // .details // .error // "unknown"), message: (.details.error // "")}' 2>/dev/null \
+    || jq -n --arg r "$ERR" '{success: false, reason: $r}'
+  exit 1
+}
+
+if printf '%s' "$RESPONSE" | jq -e '.truncated == true' >/dev/null 2>&1; then
+  printf '%s\n' "$RESPONSE"; exit 0
+fi
+
+printf '%s' "$RESPONSE" | jq -c --argjson n "$PREVIEW_CHARS" '{
+  count: (.data | length),
+  chats: [.data[] | {
+    chatId: .chat.id,
+    name: (.chat.name // .chat.id),
+    isGroup: .chat.isGroup,
+    unanswered: .unansweredCount,
+    lastKind: .lastKind,
+    lastFrom: .lastSenderName,
+    lastText: (.lastText | .[0:$n]),
+    lastAt: ((.lastMessageAt / 1000) | floor | todate)
+  }]
+}'

package/config/skills/agent/core/whatsapp-inbox/execute.test.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Tests for whatsapp-inbox — run with: bash execute.test.sh </dev/null
+# Spins up a python HTTP stub as the backend, asserts the request path the
+# skill sends and the JSON it prints. Exit 0 on pass.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+PORT=18841
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import urlparse, parse_qs
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+ENTRY = {'chat': {'id': '491@s.whatsapp.net', 'name': 'Ann', 'isGroup': False, 'lastMessageAt': 1760000000000},
+         'unansweredCount': 2, 'lastText': 'x' * 300, 'lastKind': 'text', 'lastSenderName': 'Ann', 'lastMessageAt': 1760000000000}
+class H(BaseHTTPRequestHandler):
+    def do_GET(self):
+        open(LOG, 'w').write(json.dumps({'method': 'GET', 'path': self.path, 'agent': self.headers.get('X-Agent-Session')}))
+        qs = parse_qs(urlparse(self.path).query)
+        if qs.get('limit', [''])[0] == '999':
+            self.send_response(500); self.send_header('Content-Type', 'application/json'); self.end_headers()
+            self.wfile.write(json.dumps({'success': False, 'error': 'db locked'}).encode()); return
+        self.send_response(200); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps({'success': True, 'data': [ENTRY]}).encode())
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+run() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null | jq -r '.error' 2>/dev/null; }
+
+X200=$(printf 'x%.0s' $(seq 1 200))
+WANT='{"count":1,"chats":[{"chatId":"491@s.whatsapp.net","name":"Ann","isGroup":false,"unanswered":2,"lastKind":"text","lastFrom":"Ann","lastText":"'"$X200"'","lastAt":"2025-10-09T08:53:20Z"}]}'
+
+OUT=$(run)
+check "defaults: output (preview truncated to 200)" "$OUT" "$WANT"
+check "defaults: path" "$(jq -r .path "$STUB_LOG")" "/api/whatsapp/inbox"
+check "sends the agent session header" "$(jq -r .agent "$STUB_LOG")" "test-agent"
+
+run --limit 5 --include-groups >/dev/null
+check "flags: path" "$(jq -r .path "$STUB_LOG")" "/api/whatsapp/inbox?limit=5&includeGroups=true"
+
+run '{"limit":7,"includeGroups":true}' >/dev/null
+check "json: path" "$(jq -r .path "$STUB_LOG")" "/api/whatsapp/inbox?limit=7&includeGroups=true"
+
+run --include-groups >/dev/null
+check "groups only: path" "$(jq -r .path "$STUB_LOG")" "/api/whatsapp/inbox?includeGroups=true"
+
+OUT=$(CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --limit 999 2>/dev/null); RC=$?
+check "500: exit code" "$RC" "1"
+check "500: reason" "$(printf '%s' "$OUT" | jq -r .reason)" "db locked"
+
+check "unknown option errors" "$(run_err --bogus)" "Unknown option: --bogus"
+check "--limit needs a value" "$(run_err --limit)" "--limit requires a value"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/whatsapp-read/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: WhatsApp Read
+description: Read one of the owner's WhatsApp chats, search their WhatsApp messages, or list recent chats. Read-only. For summarising and preparing replies — never for forwarding private chats elsewhere.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - generalist
+  - operations
+  - ops
+  - support
+  - sales
+triggers:
+  - read whatsapp chat
+  - search whatsapp
+  - what did they say on whatsapp
+  - whatsapp conversation
+tags:
+  - whatsapp
+  - inbox
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# WhatsApp Read
+
+```bash
+bash execute.sh --chat 4915550001@s.whatsapp.net            # newest 50 messages, oldest first
+bash execute.sh --chat 4915550001@s.whatsapp.net --before 1760000000000   # page back (use nextBefore)
+bash execute.sh --q "invoice"                                # search all chats
+bash execute.sh --chats --q "ann"                            # find a chat by name
+```
+
+## Rules (owner decision — apply to every whatsapp-* skill)
+
+- **Never send anything without the owner's explicit 「发 <code>」.** Reading is
+  all this skill does; replies go through `whatsapp-draft`, and only the owner
+  releases a draft.
+- **Never auto-reply to anyone.**
+- **Summarise; don't paste private chats wholesale** into Slack, team channels,
+  the wiki, tasks, memory or any other place. Tell the owner what a chat is
+  about and what is being asked; quote only the line you need.
+- **Groups are low priority.** Skim them only when asked or when the owner is
+  addressed directly.
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--chat` (`chatId`) | one of three | Chat JID (from `whatsapp-inbox` or `--chats`) |
+| `--q` (`q`) | one of three | Search text; with `--chats`, filters chat names |
+| `--chats` (`chats: true`) | one of three | List recent chats |
+| `--limit` (`limit`) | no | Messages default 50 (max 500); search 20 (max 200); chats 50 (max 500) |
+| `--before` (`before`) | no | Epoch ms; only older messages (paging) |
+
+## Output
+
+```json
+{"chat":{"chatId":"4915550001@s.whatsapp.net","name":"Ann","isGroup":false},
+ "messages":[{"at":"2026-09-24T18:01:00Z","fromMe":false,"sender":"Ann","kind":"text","text":"at 8?"},
+             {"at":"2026-09-24T18:02:00Z","fromMe":true,"sender":"me","kind":"text","text":"yes"}],
+ "nextBefore":null}
+```
+
+`fromMe: true` / `sender: "me"` is the owner. Media shows as its `kind`
+(`image`, `document`, `audio`, `video`, `sticker`, `other`) with the caption or
+file name as `text` — files are never downloaded. `nextBefore` is non-null when
+there may be older messages; pass it as `--before`.
+
+Search: `{"count":1,"hits":[{"chatId":"…","chatName":"Ann","at":"…","fromMe":false,"sender":"Ann","kind":"text","text":"…"}]}`
+
+## Failures
+
+`{"success":false,"reason":"chat_not_found","message":"…"}` (exit 1).

package/config/skills/agent/core/whatsapp-read/execute.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+# =============================================================================
+# whatsapp-read — Read one WhatsApp chat, search messages, or list chats
+#
+# Backed by:
+#   GET /api/whatsapp/chats/<chatId>/messages?limit=&before=   (--chat)
+#   GET /api/whatsapp/search?q=&limit=                         (--q)
+#   GET /api/whatsapp/chats?q=&limit=                          (--chats)
+# Read-only.
+#
+# Usage:
+#   bash execute.sh --chat <jid> [--limit 50] [--before <epoch ms>]
+#   bash execute.sh --q "dinner" [--limit 20]
+#   bash execute.sh --chats [--q "ann"] [--limit 50]
+#   bash execute.sh '{"chatId":"…","limit":50}' | '{"q":"dinner"}' | '{"chats":true}'
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --chat <jid> [--limit 50] [--before <epoch ms>]
+  bash execute.sh --q "text" [--limit 20]
+  bash execute.sh --chats [--q "name"] [--limit 50]
+
+Options:
+  --chat       Chat JID to read (from whatsapp-inbox / --chats)
+  --before     Page back: only messages older than this epoch-ms (use nextBefore)
+  --q          Search text (with --chats: filter chat names)
+  --chats      List recent chats instead of messages
+  --limit      Row cap
+  --help | -h  Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+CHAT=""; Q=""; LIMIT=""; BEFORE=""; LIST_CHATS=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --chat|-c)   [ $# -ge 2 ] || error_exit "--chat requires a value";   CHAT="$2";   shift 2 ;;
+    --q|--query) [ $# -ge 2 ] || error_exit "--q requires a value";      Q="$2";      shift 2 ;;
+    --limit|-n)  [ $# -ge 2 ] || error_exit "--limit requires a value";  LIMIT="$2";  shift 2 ;;
+    --before)    [ $# -ge 2 ] || error_exit "--before requires a value"; BEFORE="$2"; shift 2 ;;
+    --chats)     LIST_CHATS=1; shift ;;
+    --help|-h)   print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$CHAT" ]       && CHAT=$(printf '%s' "$INPUT" | jq -r '.chatId // .chat // empty')
+  [ -z "$Q" ]          && Q=$(printf '%s' "$INPUT" | jq -r '.q // .query // empty')
+  [ -z "$LIMIT" ]      && LIMIT=$(printf '%s' "$INPUT" | jq -r '.limit // empty')
+  [ -z "$BEFORE" ]     && BEFORE=$(printf '%s' "$INPUT" | jq -r '.before // empty')
+  [ -z "$LIST_CHATS" ] && LIST_CHATS=$(printf '%s' "$INPUT" | jq -r 'if .chats == true then "1" else "" end')
+fi
+
+uri() { jq -rn --arg v "$1" '$v|@uri'; }
+
+if [ -n "$LIST_CHATS" ]; then
+  MODE=chats
+  QS=""
+  [ -n "$Q" ] && QS="q=$(uri "$Q")"
+  [ -n "$LIMIT" ] && QS="${QS:+${QS}&}limit=$(uri "$LIMIT")"
+  ENDPOINT="/whatsapp/chats${QS:+?${QS}}"
+elif [ -n "$CHAT" ]; then
+  MODE=chat
+  QS=""
+  [ -n "$LIMIT" ] && QS="limit=$(uri "$LIMIT")"
+  [ -n "$BEFORE" ] && QS="${QS:+${QS}&}before=$(uri "$BEFORE")"
+  ENDPOINT="/whatsapp/chats/$(uri "$CHAT")/messages${QS:+?${QS}}"
+elif [ -n "$Q" ]; then
+  MODE=search
+  QS="q=$(uri "$Q")"
+  [ -n "$LIMIT" ] && QS="${QS}&limit=$(uri "$LIMIT")"
+  ENDPOINT="/whatsapp/search?${QS}"
+else
+  error_exit "Pass --chat <jid>, --q <text>, or --chats"
+fi
+
+# stderr is kept apart so lib.sh's session warning cannot pollute a good response.
+ERR_FILE=$(mktemp); trap 'rm -f "$ERR_FILE"' EXIT
+RESPONSE=$(api_call GET "$ENDPOINT" 2>"$ERR_FILE") || {
+  ERR=$(tail -n 1 "$ERR_FILE")
+  printf '%s' "$ERR" | jq -c '{success: false, reason: (.details.code // .details.error // .details // .error // "unknown"), message: (.details.error // "")}' 2>/dev/null \
+    || jq -n --arg r "$ERR" '{success: false, reason: $r}'
+  exit 1
+}
+
+if printf '%s' "$RESPONSE" | jq -e '.truncated == true' >/dev/null 2>&1; then
+  printf '%s\n' "$RESPONSE"; exit 0
+fi
+
+# One compact line per message: who, when, what.
+MSG_SHAPE='{at: ((.ts / 1000) | floor | todate), fromMe: .fromMe, sender: (if .fromMe then "me" else (.senderName // .senderJid) end), kind: .kind, text: .text}'
+
+case "$MODE" in
+  chats)
+    printf '%s' "$RESPONSE" | jq -c '{count: (.data | length), chats: [.data[] | {chatId: .id, name: (.name // .id), isGroup: .isGroup, lastAt: (if .lastMessageAt then ((.lastMessageAt / 1000) | floor | todate) else null end)}]}'
+    ;;
+  chat)
+    printf '%s' "$RESPONSE" | jq -c "{chat: {chatId: .data.chat.id, name: (.data.chat.name // .data.chat.id), isGroup: .data.chat.isGroup}, messages: [.data.messages[] | ${MSG_SHAPE}], nextBefore: .data.nextBefore}"
+    ;;
+  search)
+    printf '%s' "$RESPONSE" | jq -c "{count: (.data | length), hits: [.data[] | ({chatId: .chatId, chatName: (.chatName // .chatId)} + ${MSG_SHAPE})]}"
+    ;;
+esac