@floomhq/signaldash 0.43.0 → 0.43.1

package/README.md

@@ -121,7 +121,7 @@ setup installs both from the same pinned npm package
 the human chose to execute:
 
 ```bash
-npx -y @floomhq/signaldash@0.43.0 <invite-code>
+npx -y @floomhq/signaldash@0.43.1 <invite-code>
 ```
 
 Run that command in a terminal, not in an agent chat. Do not ask an agent to
@@ -201,7 +201,7 @@ timer, scheduler entry, Buffer item, or provider write.
 - `sd_withdrawal_batch_approve(withdrawal_batch_id, confirm_token)`
 - `sd_withdrawal_batch_cancel(withdrawal_batch_id, approval_view_hash, confirm)`
 - `wa_list_chats`
-- `wa_read_messages(chat_id)`
+- `wa_read_messages(chat_id, limit?, cursor?)`
 - `wa_mark_read(chat_id)`
 - `wa_get_attachment(chat_id, message_id, attachment_id)`
 - `wa_transcribe_voice(chat_id, message_id, attachment_id)`
@@ -209,6 +209,42 @@ timer, scheduler entry, Buffer item, or provider write.
 - `wa_send_message(chat_id, text?, attachments?, expected_watermark?, mark_read?)` — confirmed sends clear unread by default; `mark_read:false` preserves unread.
 - `wa_delete_message(chat_id, message_id)`
 - `wa_delete_messages(messages)`
+
+WhatsApp history is paginated, not limited to the newest 100 messages. Read
+`wa_read_messages` with `limit:250`, then pass the exact returned `cursor`
+unchanged to the same chat to read older pages. Each call fetches at most one
+provider message page; there is no automatic bulk scan. Pace requests, set a
+finite page/message budget, and stop on provider warnings, authentication
+errors, 403/429, a repeated cursor, or an explicit null cursor. Empty pages
+with a new cursor can still lead to more history.
+
+The provider's `items` or `messages` envelope and cursor are preserved.
+`history_pagination` reports `response_shape_supported`, requested limit, returned item count, next cursor,
+`has_more` (null when unknown), `provider_exhausted`, and `cursor_advancing`.
+Only an explicit null cursor on a recognized list proves provider exhaustion;
+missing pagination or an unfamiliar envelope is unknown, never proof that a
+message does not exist. Even exhausted provider history may be incomplete if
+older history was never synchronized by the provider.
+
+Continuation cursors must have been issued to this authenticated user, account
+and exact chat. They live in a bounded in-memory registry for 60 minutes;
+restart, expiry or an unissued/wrong-scope cursor requires a fresh first page
+without cursor. At most one read per cursor runs concurrently. Successful
+continuation consumes that receipt and registers the next cursor atomically;
+provider/validation failures preserve it for retry. Registry bounds are 4,096
+globally, 512 per user and 128 per account/chat, with no live-entry eviction.
+Capacity returns an explicit error. Invalid provider cursors, mismatched
+account/chat rows and unsupported historical response shapes are refused
+without returning message contents.
+
+Cursor pages return `history_page:true` and `current_watermark:null`. They
+neither create nor refresh a send-read proof nor update reply/contact
+observations or mark the chat read. Existing latest-page proofs are preserved.
+Before sending, read the latest page again **without cursor**. Cursor support
+does not change provider base URLs/API versions, send budgets, or account limits.
+The default stays 30 messages. WhatsApp's explicit per-page maximum is 250,
+matching the [provider's message endpoint](https://developer.unipile.com/reference/chatscontroller_listchatmessages.md);
+LinkedIn/Instagram reads and chat-list caps remain 100.
 - `ig_list_chats(limit?, cursor?, search?, max_scan?, unread?)`
 - `ig_read_messages(chat_id, limit?)`
 - `ig_mark_read(chat_id)`

package/bin/sd.mjs

@@ -1504,12 +1504,13 @@ const TOOLS = [
     name: "wa_read_messages",
     ch: "wa",
     action: "read",
-    description: "Read messages and the resolved chat in one WhatsApp thread. Messages include sender_name where the exact sender can be resolved. args: chat_id",
+    description: "Read one bounded page of messages and the resolved WhatsApp chat. Use limit up to 250 and the returned cursor to reach older history, one paced page at a time. Cursor pages never authorize sends or update reply observations; read without cursor immediately before sending. Missing history is not proof of absence. args: chat_id, limit, cursor",
     inputSchema: {
       type: "object",
       properties: {
         chat_id: { type: "string", minLength: 1, maxLength: 500 },
-        limit: { type: "integer", minimum: 1, maximum: 100 },
+        limit: { type: "integer", minimum: 1, maximum: 250 },
+        cursor: { type: "string", minLength: 1, maxLength: 4000, description: "Exact opaque cursor from the preceding page, unchanged. Omit for the latest page." },
       },
       required: ["chat_id"],
       additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/signaldash",
-  "version": "0.43.0",
+  "version": "0.43.1",
   "description": "Secure LinkedIn, WhatsApp, and email access for AI agents",
   "type": "module",
   "bin": {

package/skills/signaldash/SKILL.md

@@ -446,7 +446,7 @@ Use the exact tool names and argument keys below. Limits are optional.
 | `sd_withdrawal_batch_approve` | `withdrawal_batch_id` required; `confirm_token` required in the exact `sd-xxxx-xxxx-xxxx` form the human read off the approval page | Record the human's approval using the single-use code that authenticated page minted for them. An agent cannot mint, guess, or bypass that code. |
 | `sd_withdrawal_batch_cancel` | `withdrawal_batch_id` required; `approval_view_hash` required string or null exactly as inspected; `confirm:true` required | Revoke the approval and stop every withdrawal that has not started. It cannot recall one already submitted, and it cannot restore the three-week re-invite block for people already withdrawn. |
 | `wa_list_chats` | `limit` integer 1-100, default 20; `cursor` optional; `search` optional string, max 200 characters; `max_scan` optional integer 1-500, default 200, and never more than five provider pages | Find an existing WhatsApp conversation and exact `chat_id`. Direct chats expose a resolved contact in both `name` and `attendee_name` when available; groups retain their provider group `name` and return `attendee_name:null`. With `search` it filters case-insensitively on `name`, `subject`, `id`, `provider_id`, `attendee_provider_id`, `attendee_public_identifier`, and `attendee_name`. The attendee identifiers can carry a phone JID or `@lid`, and digit normalization makes bare or formatted identifiers match their stored form, such as `+49 151 67609512`, `004915167609512`, `4915167609512@s.whatsapp.net`, or the bare digits from `202726935924973@lid`. The provider CANNOT filter a chat list, so SignalDash scans and filters: read `search.exhaustive` before you conclude anything, `search.limit_reached` to know whether the matches were truncated by `limit`, and `search.searched_fields` for what was actually compared. `false` means "not among the `scanned_chats` scanned", never "does not exist" -- continue from the returned `cursor`. When `started_from_cursor` is true the scan began mid-list, so even `exhaustive` says nothing about the chats before that cursor. Search an exact phone number, lid, or known attendee name rather than guessing. Any other key, including `text` and `member_id`, is refused with `unsupported_parameter`. |
-| `wa_read_messages` | `chat_id` required; `limit` 1-100, default 30 | Verify a WhatsApp contact and recent history before summarizing, drafting, or sending. The response includes `current_watermark` for an exact compare-and-swap send. |
+| `wa_read_messages` | `chat_id` required; `limit` 1-250, default 30; optional `cursor` from the previous page, unchanged, max 4000 characters | Read one bounded WhatsApp page. Start without cursor; follow issued `history_pagination.next_cursor` with paced calls and a finite page/message budget. Historical pages return `history_page:true`, `current_watermark:null`, and never refresh send-read proofs or reply/contact observations. Cursors are scoped to this user/account/chat, expire after 60 minutes or restart, and permit one active read at a time; an invalid cursor requires a fresh first page. Inspect `has_more`, `provider_exhausted`, and `cursor_advancing`; missing pagination is unknown, not absence, and repeated cursors require stopping. Stop on provider warnings, authentication errors or 403/429. Read the latest page again without cursor before sending. |
 | `wa_mark_read` | `chat_id` required | Explicitly clear one WhatsApp chat's unread state. Reading never clears unread automatically. |
 | `wa_get_attachment` | `chat_id`, `message_id`, `attachment_id` all required, max 500 characters each | Download one attachment of one message in a chat this account owns. Read the chat first: the exact `message_id` and `attachment_id` come from `wa_read_messages`. Returns the stored path on the SignalDash host, mimetype, byte size and sha256. |
 | `wa_transcribe_voice` | `chat_id`, `message_id`, `attachment_id` all required, max 500 characters each; `backend` optional, exactly `gemini` or `whisper` | Turn one WhatsApp voice note into text through SignalDash instead of fetching provider bytes yourself. Always read the returned `backend`: `gemini` is the accurate default, `whisper-small` is the weak local fallback and mangles German with English terms mixed in, and a fallback also carries `fallback_reason`. Non-audio attachments are refused with `415 not_audio`; an unknown backend with `400 unknown_backend`; a transcription that exceeds its time limit returns `504 transcription_timeout` with the stored audio path. |