@lofa199419/waha-v2 2026.3.4 → 2026.3.6

package/SESSION_HANDOFF_2026-03-05.md

@@ -0,0 +1,55 @@
+# WAHA v2 Session Handoff (2026-03-05)
+
+## 1) Scope completed
+- Focused only on `extensions/waha-v2`.
+- Objective was to make typing indicator + chunked sending behavior reliable and observable, then publish and verify on target host.
+
+## 2) Local code changes made
+
+### `src/client.ts`
+- Improved typing presence calls (`startTyping` / `stopTyping`) so non-2xx HTTP responses are treated as failures.
+- Added response-context error reporting for easier diagnosis.
+
+### `src/webhook.ts`
+- Added debug logs around typing/chunk lifecycle to make runtime behavior visible.
+- Ensured inter-chunk typing start failures do **not** break chunk sending.
+- Updated behavior to trigger typing before first chunk and added a short first-chunk delay (`700ms`) to make typing indicator visible.
+
+## 3) Publish
+- Published npm package: `@lofa199419/waha-v2@2026.3.5`.
+- Registry was verified to reflect `2026.3.5`.
+
+## 4) Remote deployment performed
+Target host used:
+- `ubuntu@100.106.66.110`
+
+State found before fix:
+- Host still had `waha-v2@2026.3.4` in `~/.openclaw/extensions/waha-v2`.
+- Typing config block not set.
+
+Actions performed:
+- Updated extension on host to `2026.3.5`.
+- Set config values:
+  - `channels.waha-v2.typing.enabled=true`
+  - `channels.waha-v2.typing.chunking=true`
+  - `channels.waha-v2.typing.charsPerSecond=25`
+  - `channels.waha-v2.typing.maxChunkLength=220`
+- Restarted gateway.
+
+Post-update verification:
+- Plugin list shows `waha-v2@2026.3.5`.
+- Typing config present.
+- WAHA channel/accounts probing healthy.
+
+## 5) Remaining validation step
+- Final observational confirmation: send a multi-paragraph prompt and verify logs show typing/chunk markers during a real message.
+
+Suggested log check pattern:
+- `waha-v2: send chunked reply`
+- `waha-v2: send chunk`
+- `typing start ok`
+- `typing stop ok`
+- first/inter-chunk typing start success/failure markers
+
+## 6) Environment note
+- On the remote host, `rg` was unavailable; use `grep`/`grep -E` for log filtering.

package/SESSION_HANDOFF_2026-03-05_E2E_STATUS.md

@@ -0,0 +1,84 @@
+# WAHA v2 E2E Status Handoff (2026-03-05)
+
+## Scope
+This note captures what was smoke tested live in this session, what is confirmed, what is partially confirmed, and what remains to verify later.
+
+## Environment used
+- Repo: `/home/lofa/dev/openclaw`
+- Extension focus: `extensions/waha-v2`
+- Active account: `default`
+- Main WAHA session: `finaltouch`
+
+## Code changes completed in this session
+
+### 1) Target/action routing hardening (core)
+- For no-target actions, accidental `target` no longer hard-fails.
+  - File: `src/infra/outbound/channel-target.ts`
+- WAHA group/contact action target modes fixed so `target` maps correctly.
+  - File: `src/infra/outbound/message-action-spec.ts`
+- Regression tests added/updated.
+  - File: `src/infra/outbound/message-action-runner.test.ts`
+
+### 2) Request-code flow in WAHA v2 plugin
+- `request-code` now enforces session prep + delay flow:
+  - Missing session: create -> start
+  - Existing active session: stop -> start (restart)
+  - Existing stopped/failed session: start
+  - Wait 5 seconds
+  - Request code
+- File: `extensions/waha-v2/src/channel.ts`
+
+## Live smoke tests run and result
+
+### A) Messaging/chat/group/contact core read paths
+- PASS: `list-chats`
+- PASS: `get-chat-messages` (chat `154739484418169@lid`)
+- PASS: `react` on message `false_154739484418169@lid_3A6FC76D1349CFCA7C1D` with `👍`
+- PASS: `list-groups`
+- PASS: `get-group`
+- PASS: `get-group-participants`
+- PASS: `get-group-invite-code`
+- PASS: `list-contacts`
+- PASS: `check-contact` for known number `573016924546`
+- PASS: `get-contact` (known resolved contact id)
+
+### B) Session/pairing E2E
+- PASS: `start-session` on primary (`finaltouch`)
+- PASS: fresh session create/start/get-qr flow
+  - temporary session: `e2e-smoke-1772739741688`
+- PASS: request-code sequence with 5s delay for number `905382188346`
+  - temporary session: `pair-code-1772740042905`
+  - returned code: `J7CR-WTK7`
+- NOTE: `startSession` on a fresh non-existent session fails first with `Resource not found` (expected), then succeeds after create.
+
+## Not fully confirmed / lower confidence areas
+
+### WAHA server-side failures seen (likely backend/permission/input related, not mapping)
+- `promote-group-admin` / `demote-group-admin` on real group + participant returned WAHA 500.
+- mutation ops with fake/nonexistent ids returned WAHA 500 (expected pattern).
+- `check-contact` for obviously unknown number returned WAHA 500 (not a clean false response).
+
+### Explicitly not required right now (per user)
+- block/unblock round-trip verification
+
+## 100% verified for current priority (practical)
+Priority list from user context:
+- Start a Session -> verified
+- Get QR Code for Pairing -> verified
+- Request Pairing Code -> verified (with required wait behavior)
+- Send a Message -> verified
+- React to a Message -> verified
+- List Conversations -> verified
+- Check Contact Status -> verified on known-valid contact
+
+## Remaining to double-check later (if needed)
+1. `request-code` through the full OpenClaw message action runner path (not only direct wrapper script) after publishing latest plugin/core changes everywhere.
+2. clean handling expectations for unknown numbers in `check-contact` (whether WAHA should return false vs 500; depends on backend behavior).
+3. admin-role mutation behavior (`promote/demote`) with a dedicated controlled test group where bot permissions are guaranteed.
+
+## Operational notes
+- Temporary sessions created during tests were stopped.
+- Last active primary session remains `finaltouch`.
+- Existing older summary file remains:
+  - `extensions/waha-v2/SESSION_HANDOFF_2026-03-05.md`
+

package/index.ts

@@ -1,8 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { wahaV2Plugin } from "./src/channel.js";
-import { setWahaV2Runtime } from "./src/runtime.js";
-import { handleWahaV2WebhookRequest } from "./src/webhook.js";
 import {
   handleWahaV2QrRoute,
   handleWahaV2RequestCodeRoute,
@@ -15,7 +13,9 @@ import {
   WAHA_V2_ROUTE_STATUS,
   WAHA_V2_ROUTE_WAIT,
 } from "./src/routes.js";
+import { setWahaV2Runtime } from "./src/runtime.js";
 import { WAHA_V2_WEBHOOK_BASE } from "./src/types.js";
+import { handleWahaV2WebhookRequest } from "./src/webhook.js";
 
 const plugin = {
   id: "waha-v2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lofa199419/waha-v2",
-  "version": "2026.3.4",
+  "version": "2026.3.6",
   "private": false,
   "description": "OpenClaw WAHA v2 channel plugin — independent WhatsApp HTTP API integration",
   "type": "module",
@@ -13,7 +13,9 @@
     "openclaw": ">=2026.0.0"
   },
   "peerDependenciesMeta": {
-    "openclaw": { "optional": true }
+    "openclaw": {
+      "optional": true
+    }
   },
   "openclaw": {
     "extensions": [

package/skills/waha-v2/SKILL.md

@@ -19,43 +19,74 @@ Use the `message` tool with `channel: "waha-v2"`. You have complete WhatsApp acc
 
 ## Session States
 
-| State | Meaning |
-|---|---|
-| `WORKING` / `CONNECTED` | Ready — go ahead |
-| `STOPPED` / `FAILED` | Call `start-session` first |
+| State                      | Meaning                                   |
+| -------------------------- | ----------------------------------------- |
+| `WORKING` / `CONNECTED`    | Ready — go ahead                          |
+| `STOPPED` / `FAILED`       | Call `start-session` first                |
 | `SCAN_QR_CODE` / `PAIRING` | Waiting for user to scan QR or enter code |
-| `CONNECTING` | Starting up — wait briefly |
+| `CONNECTING`               | Starting up — wait briefly                |
 
 ---
 
 ## Sending Messages
 
 ### Text
+
 ```json
 { "action": "send", "channel": "waha-v2", "to": "15550001234@c.us", "message": "Hello!" }
 ```
 
 ### Media (image / video / audio / file)
+
 ```json
-{ "action": "send", "channel": "waha-v2", "to": "15550001234@c.us", "media": "https://…/file.pdf", "message": "Your report" }
+{
+  "action": "send",
+  "channel": "waha-v2",
+  "to": "15550001234@c.us",
+  "media": "https://…/file.pdf",
+  "message": "Your report"
+}
 ```
 
 ### Poll
+
 ```json
-{ "action": "poll", "channel": "waha-v2", "to": "15550001234@c.us", "pollQuestion": "Which day?", "pollOption": ["Mon","Wed","Fri"], "pollMulti": false }
+{
+  "action": "poll",
+  "channel": "waha-v2",
+  "to": "15550001234@c.us",
+  "pollQuestion": "Which day?",
+  "pollOption": ["Mon", "Wed", "Fri"],
+  "pollMulti": false
+}
 ```
 
 ### Location
+
 ```json
-{ "action": "send-location", "channel": "waha-v2", "to": "15550001234@c.us", "latitude": 37.77, "longitude": -122.41, "title": "SF Office" }
+{
+  "action": "send-location",
+  "channel": "waha-v2",
+  "to": "15550001234@c.us",
+  "latitude": 37.77,
+  "longitude": -122.41,
+  "title": "SF Office"
+}
 ```
 
 ### Contact card
+
 ```json
-{ "action": "send-contact", "channel": "waha-v2", "to": "15550001234@c.us", "contacts": [{ "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Alice\nTEL:+14155559999\nEND:VCARD" }] }
+{
+  "action": "send-contact",
+  "channel": "waha-v2",
+  "to": "15550001234@c.us",
+  "contacts": [{ "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Alice\nTEL:+14155559999\nEND:VCARD" }]
+}
 ```
 
 ### Forward a message
+
 ```json
 { "action": "forward-message", "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
 ```
@@ -152,11 +183,13 @@ Use the `message` tool with `channel: "waha-v2"`. You have complete WhatsApp acc
 ## Session Management & Login Flow
 
 ### Full QR login sequence
+
 1. `start-session` — if `alreadyConnected: true`, done.
 2. `get-qr` — returns `{ data }` base64 PNG; show to user to scan in WhatsApp → Linked Devices.
 3. User scans, then call `start-session` again to confirm `connected: true`.
 
 ### Pairing code (no phone camera)
+
 1. `start-session`
 2. `request-code` with `phoneNumber: "15550001234"` — returns 8-digit code.
 3. User enters code in WhatsApp → Linked Devices → Link with phone number.
@@ -171,7 +204,13 @@ Use the `message` tool with `channel: "waha-v2"`. You have complete WhatsApp acc
 ## Multi-Account
 
 ```json
-{ "action": "send", "channel": "waha-v2", "accountId": "secondary", "to": "15550001234@c.us", "message": "Hi" }
+{
+  "action": "send",
+  "channel": "waha-v2",
+  "accountId": "secondary",
+  "to": "15550001234@c.us",
+  "message": "Hi"
+}
 ```
 
 Each account gets its own webhook: `{webhookUrl}/{accountId}`.

package/src/accounts.ts

@@ -60,6 +60,7 @@ export function resolveWahaV2Account(
     enabled: account.enabled !== false,
     dmPolicy: account.dmPolicy,
     allowFrom: account.allowFrom,
+    typing: account.typing,
   };
 }
 
@@ -102,7 +103,10 @@ export function setWahaV2AccountEnabled(
     // Single-account mode — set enabled on root.
     return setWahaV2ChannelConfig(cfg, { ...root, enabled });
   }
-  const accounts = { ...(root.accounts ?? {}), [accountId]: { ...(root.accounts?.[accountId] ?? {}), enabled } };
+  const accounts = {
+    ...(root.accounts ?? {}),
+    [accountId]: { ...(root.accounts?.[accountId] ?? {}), enabled },
+  };
   return setWahaV2ChannelConfig(cfg, { ...root, accounts });
 }
 
@@ -113,5 +117,8 @@ export function deleteWahaV2Account(cfg: OpenClawConfig, accountId: string): Ope
   }
   const accounts = { ...root.accounts };
   delete accounts[accountId];
-  return setWahaV2ChannelConfig(cfg, { ...root, accounts: Object.keys(accounts).length > 0 ? accounts : undefined });
+  return setWahaV2ChannelConfig(cfg, {
+    ...root,
+    accounts: Object.keys(accounts).length > 0 ? accounts : undefined,
+  });
 }

package/src/channel.ts

@@ -8,12 +8,12 @@ import {
   setWahaV2AccountEnabled,
   setWahaV2ChannelConfig,
 } from "./accounts.js";
+import { wahaV2ChannelConfigSchema } from "./config-schema.js";
 import { wahaV2Gateway } from "./gateway.js";
 import { acquireLoginLock, releaseLoginLock, waitForWahaV2Connected } from "./login.js";
 import { wahaV2Outbound } from "./outbound.js";
 import { probeWahaV2Session } from "./probe.js";
 import { getWahaV2Client } from "./runtime.js";
-import { wahaV2ChannelConfigSchema } from "./config-schema.js";
 import {
   WAHA_V2_CHANNEL_ID,
   WAHA_V2_DEFAULT_ACCOUNT_ID,
@@ -22,6 +22,48 @@ import {
   type WahaV2RootConfig,
 } from "./types.js";
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function prepareSessionForRequestCode(params: {
+  client: NonNullable<ReturnType<typeof getWahaV2Client>>;
+  session: string;
+}): Promise<{
+  sessionExisted: boolean;
+  previousStatus: string | null;
+  restarted: boolean;
+}> {
+  const sessions = await params.client.listSessions(true).catch(() => []);
+  const current = sessions.find((entry) => String(entry?.name ?? "") === params.session);
+  const previousStatus = current && typeof current.status === "string" ? current.status : null;
+  const sessionExisted = Boolean(current);
+  let restarted = false;
+
+  if (!sessionExisted) {
+    await params.client.createSession(params.session);
+    await params.client.startSession(params.session);
+    return { sessionExisted, previousStatus, restarted };
+  }
+
+  const normalized = String(previousStatus ?? "").trim().toUpperCase();
+  const shouldRestart =
+    normalized.length > 0 &&
+    !["STOPPED", "FAILED", "NONE", "UNKNOWN", "DISCONNECTED"].includes(normalized);
+
+  if (shouldRestart) {
+    await params.client.stopSession(params.session).catch(() => {});
+    restarted = true;
+  }
+
+  await params.client.startSession(params.session).catch(async () => {
+    await params.client.createSession(params.session);
+    await params.client.startSession(params.session);
+  });
+
+  return { sessionExisted, previousStatus, restarted };
+}
+
 /** Normalize allow-from entries to WhatsApp JID format. */
 function normalizeAllowEntry(entry: string): string {
   const trimmed = entry.trim();
@@ -142,8 +184,7 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
       allowFrom: account.allowFrom,
     }),
 
-    resolveAllowFrom: ({ cfg, accountId }) =>
-      resolveWahaV2Account(cfg, accountId).allowFrom,
+    resolveAllowFrom: ({ cfg, accountId }) => resolveWahaV2Account(cfg, accountId).allowFrom,
 
     formatAllowFrom: ({ allowFrom }) =>
       allowFrom.map((e) => normalizeAllowEntry(String(e))).filter(Boolean),
@@ -220,7 +261,13 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
       }
       // Contact lookup / block
       if (gate("contacts")) {
-        result.push("list-contacts", "get-contact", "check-contact", "block-contact", "unblock-contact");
+        result.push(
+          "list-contacts",
+          "get-contact",
+          "check-contact",
+          "block-contact",
+          "unblock-contact",
+        );
       }
       // Group management
       if (gate("groups")) {
@@ -280,7 +327,9 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
           await client.startSession(session).catch(async () => {
             await client.createSession(session);
           });
-          const waitResult = await waitForWahaV2Connected(client, session, 5_000).catch(() => ({ ok: false }));
+          const waitResult = await waitForWahaV2Connected(client, session, 5_000).catch(() => ({
+            ok: false,
+          }));
           const probe = await probeWahaV2Session(client, session).catch(() => ({ ok: false }));
           return jsonResult({
             ok: true,
@@ -312,8 +361,20 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
         if (!phoneNumber) throw new Error("waha-v2: request-code requires params.phoneNumber");
         acquireLoginLock(account.accountId);
         try {
+          const prep = await prepareSessionForRequestCode({ client, session });
+          // Give WAHA a short transition window before requesting pairing code.
+          await sleep(5_000);
           const result = await client.requestCode(session, phoneNumber);
-          return jsonResult({ ok: true, action: "request-code", session, code: result?.code ?? null });
+          return jsonResult({
+            ok: true,
+            action: "request-code",
+            session,
+            sessionExisted: prep.sessionExisted,
+            previousStatus: prep.previousStatus,
+            restarted: prep.restarted,
+            waitedMs: 5_000,
+            code: result?.code ?? null,
+          });
         } finally {
           releaseLoginLock(account.accountId);
         }
@@ -367,7 +428,8 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
       if (action === "forward-message") {
         const chatId = String(p.to ?? p.chatId ?? "");
         const messageId = String(p.messageId ?? "");
-        if (!chatId || !messageId) throw new Error("waha-v2: forward-message requires to and messageId");
+        if (!chatId || !messageId)
+          throw new Error("waha-v2: forward-message requires to and messageId");
         const result = await client.forwardMessage(session, chatId, messageId);
         return jsonResult({ ok: true, action: "forward-message", chatId, result });
       }
@@ -390,7 +452,8 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
         const chatId = String(p.to ?? p.chatId ?? "");
         const messageId = String(p.messageId ?? "");
         const text = String(p.text ?? "");
-        if (!chatId || !messageId || !text) throw new Error("waha-v2: edit requires to, messageId, text");
+        if (!chatId || !messageId || !text)
+          throw new Error("waha-v2: edit requires to, messageId, text");
         await client.editMessage(session, chatId, messageId, text);
         return jsonResult({ ok: true, action: "edit", chatId, messageId });
       }
@@ -441,7 +504,8 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
       if (action === "get-message") {
         const chatId = String(p.to ?? p.chatId ?? "");
         const messageId = String(p.messageId ?? "");
-        if (!chatId || !messageId) throw new Error("waha-v2: get-message requires to and messageId");
+        if (!chatId || !messageId)
+          throw new Error("waha-v2: get-message requires to and messageId");
         const message = await client.getChatMessage(session, chatId, messageId);
         return jsonResult({ ok: true, action: "get-message", chatId, messageId, message });
       }
@@ -570,16 +634,22 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
 
       if (action === "promote-group-admin") {
         const groupId = String(p.groupId ?? p.to ?? "");
-        const participants = Array.isArray(p.participants) ? (p.participants as string[]) : [String(p.participant ?? "")].filter(Boolean);
-        if (!groupId || participants.length === 0) throw new Error("waha-v2: promote-group-admin requires groupId and participants");
+        const participants = Array.isArray(p.participants)
+          ? (p.participants as string[])
+          : [String(p.participant ?? "")].filter(Boolean);
+        if (!groupId || participants.length === 0)
+          throw new Error("waha-v2: promote-group-admin requires groupId and participants");
         const result = await client.promoteGroupAdmin(session, groupId, participants);
         return jsonResult({ ok: true, action: "promote-group-admin", groupId, result });
       }
 
       if (action === "demote-group-admin") {
         const groupId = String(p.groupId ?? p.to ?? "");
-        const participants = Array.isArray(p.participants) ? (p.participants as string[]) : [String(p.participant ?? "")].filter(Boolean);
-        if (!groupId || participants.length === 0) throw new Error("waha-v2: demote-group-admin requires groupId and participants");
+        const participants = Array.isArray(p.participants)
+          ? (p.participants as string[])
+          : [String(p.participant ?? "")].filter(Boolean);
+        if (!groupId || participants.length === 0)
+          throw new Error("waha-v2: demote-group-admin requires groupId and participants");
         const result = await client.demoteGroupAdmin(session, groupId, participants);
         return jsonResult({ ok: true, action: "demote-group-admin", groupId, result });
       }
@@ -602,12 +672,14 @@ export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
         const groupId = String(p.groupId ?? p.to ?? "");
         if (action === "renameGroup") {
           const subject = String(p.name ?? p.subject ?? "");
-          if (!groupId || !subject) throw new Error("waha-v2: renameGroup requires groupId and name");
+          if (!groupId || !subject)
+            throw new Error("waha-v2: renameGroup requires groupId and name");
           await client.updateGroupSubject(session, groupId, subject);
           return jsonResult({ ok: true, action: "renameGroup", groupId });
         }
         const description = String(p.description ?? "");
-        if (!groupId || !description) throw new Error("waha-v2: update-group-description requires groupId and description");
+        if (!groupId || !description)
+          throw new Error("waha-v2: update-group-description requires groupId and description");
         await client.updateGroupDescription(session, groupId, description);
         return jsonResult({ ok: true, action: "update-group-description", groupId });
       }