@floomhq/signaldash 0.22.0 → 0.28.0

package/README.md

@@ -52,7 +52,7 @@ npx -y @floomhq/signaldash connect linkedin claim <account_id>
 Paste this command into a terminal:
 
 ```bash
-claude mcp add signaldash -- npx -y @floomhq/signaldash mcp
+claude mcp add signaldash -s user -- npx -y @floomhq/signaldash mcp
 ```
 
 ### Cursor
@@ -82,20 +82,25 @@ The MCP server uses the user token created by `login`. It cannot access a
 LinkedIn, WhatsApp, or email account until that channel has been connected for
 the same logged-in user.
 
-## Give the agent the operating skill
+## Operating skill distribution
 
 The canonical [`signaldash` skill](skills/signaldash/SKILL.md) teaches an agent
 when to use SignalDash, how to persist the skill, complete setup, interpret
 connection state, operate every tool, handle server guards, and run safe worked
-flows. It is also served as raw Markdown for agents at:
+flows. The one-command setup installs the skill from the same pinned npm package
+the human chose to execute:
 
-```text
-https://signaldash.dev/SKILL.md
+```bash
+npx -y @floomhq/signaldash@0.28.0 <invite-code>
 ```
 
-The one-command setup installs the bundled copy into Claude Code. Other clients
-must save the skill in their documented skill directory and reload skill
-discovery. The narrower
+Run that command in a terminal, not in an agent chat. Do not ask an agent to
+fetch a remote `SKILL.md` and install it as trusted instructions. The public
+`https://signaldash.dev/SKILL.md` endpoint remains available for transparent
+human review only.
+
+Other clients can install the reviewed bundled file from the package into their
+documented skill directory and reload skill discovery. The narrower
 [`signaldash-safe-usage` skill](skills/signaldash-safe-usage/SKILL.md) remains
 available for clients that separate operating and send-safety instructions.
 
@@ -116,25 +121,169 @@ SignalDash exposes:
 - `sd_settings_get()`
 - `sd_settings_set(auto_accept_linkedin, auto_accept_linkedin_filters?, confirm)`
 - `sd_auto_accept_status()`
+- `sd_voice_profile(channel, force_recompute?)`
 - `li_search_connections(query, filters?, limit?)`
 - `li_discover_people(query, filters?, limit?, confirm?)`
 - `li_create_invitation_batch(source_label, time_zone, targets)`
 - `li_get_invitation_batch(batch_id)`
 - `li_cancel_invitation_batch(batch_id, approval_view_hash, confirm)`
+- `sd_campaign_create(source_label, time_zone, messages, target_source?, targets?, engagers?, invite_ttl_days?)`
+- `sd_campaign_preview(campaign_id)`
+- `sd_campaign_approve(campaign_id, confirm_token)`
+- `sd_campaign_status(campaign_id)`
+- `sd_campaign_cancel(campaign_id, approval_view_hash, confirm)`
+- `sd_withdrawal_batch_create(account, exclude, time_zone, older_than_days?, limit?, source_label?, allow_unmatched_exclusions?)`
+- `sd_withdrawal_batch_status(withdrawal_batch_id)`
+- `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_send_message(chat_id, text)`
+- `wa_get_attachment(chat_id, message_id, attachment_id)`
+- `wa_transcribe_voice(chat_id, message_id, attachment_id)`
+- `wa_send_message(chat_id, text?, attachments?)`
+- `wa_delete_message(chat_id, message_id)`
+- `wa_delete_messages(messages)`
 - `email_list(limit)`
 - `email_read(thread_id, limit)`
 - `email_send(to, subject, body)`
 - `li_my_posts(limit, member_id)`
 - `li_post_reactions(post_id, limit)`
 - `li_post_comments(post_id, limit)`
-- `li_draft_post(text, publish)`
+- `li_draft_post(text, publish, scheduled_at?, mentions?, attachments?, first_comment?)`
+- `li_set_scheduled_post_first_comment(id, first_comment, confirm)`
+- `li_scheduled_posts()`
+- `li_cancel_scheduled_post(id, confirm)`
+- `sd_schedule_message(channel, chat_id, text, scheduled_at, confirm)`
+- `sd_scheduled_messages(state?, channel?)`
+- `sd_cancel_scheduled_message(id, confirm)`
 
 Every operation runs through the hosted SignalDash backend. Agents never
 receive the Unipile access key.
 
+A WhatsApp message can carry files. `wa_send_message` takes up to 4 exact
+`{filename, content_type, content_base64}` attachments, at most 16 MiB per file
+and 16 MiB per message, and accepts PNG, JPEG, WebP, GIF, PDF, CSV, plain text,
+JSON, xlsx and zip. `text` is the caption and may be omitted when a file is
+attached, but a call carrying neither text nor an attachment is refused rather
+than sent as an empty message. There is no attachment lane: a send with a file
+runs the same ownership check, the same read-before-send guard, the same
+duplicate guard and the same daily budget as a text send, and is recorded the
+same way. Files are validated before anything is reserved, so a malformed or
+oversized attachment costs no send budget and never reaches the provider, and
+every refusal names the exact rule and the exact file that tripped it. Nothing
+is ever truncated or dropped silently. LinkedIn messages carry text only, and
+`li_send_message` refuses an `attachments` argument instead of ignoring it.
+
+A recent read is no longer sufficient on its own. A message send re-reads the
+thread immediately before sending and refuses with `409 thread_changed` unless
+it is still the exact thread that was read, which is the guard LinkedIn has
+always had and WhatsApp did not: a 30-minute read window is satisfied just as
+comfortably by a conversation that moved 29 minutes ago as by one nobody has
+touched, and a reply that arrived in between is precisely when a draft stops
+being the right thing to send. The comparison is a hash over the page that was
+read, taken at the same item limit, so the re-read has to match message for
+message. A chat whose most recent read predates this guard carries no such hash
+and is refused with `428 read_before_send_required` until it is read again,
+rather than waved through on a timestamp that cannot answer the question. If the
+re-read itself fails, the send is refused with
+`502 thread_preflight_unavailable`: whether the thread changed is then unknown,
+and unknown is not permission. All three refusals happen before anything is
+reserved, so none of them costs send budget.
+
+A provider answer this process cannot read counts as a re-read that failed, not
+as an empty conversation. Only the two documented list envelopes are hashed;
+anything else yields no hash at all, so a read that hits a drifted shape records
+no authorization (the next send is refused at `428`) and a re-read that hits one
+refuses at `502` rather than being compared. That distinction is the whole
+guard: hashing an unrecognised answer to the hash of an empty thread would let a
+read and a re-read that had both seen nothing agree with each other and satisfy
+the requirement that a human looked at the conversation.
+
+A send is not idempotent, so an unconfirmed one is not silently retryable. If
+the provider times out, fails with a 5xx, or answers 2xx with a body that will
+not parse, the message may well have been delivered: SignalDash records the
+attempt before the request leaves and refuses an identical retry with
+`409 send_outcome_unknown`. Read the chat again, and only if the message is
+genuinely absent, resend the identical payload with `confirm_resend:true`. That
+re-read is enforced rather than merely instructed: a resend whose most recent
+read of the chat predates the failed attempt is refused with
+`428 reread_after_failed_send_required`, since a read taken beforehand cannot
+show whether the message arrived. Time does not
+clear that record, because waiting does not turn a delivered message into an
+undelivered one; only the caller confirming what the thread actually shows
+does. A provider that answers with a 4xx refused the message outright, so that
+record is cleared and the send stays retryable. Two 4xx answers are excepted,
+as a judgement call rather than on documented provider semantics: `408` and
+`429` can both arrive after a message was already accepted and forwarded, so
+they are treated as unknown outcomes too.
+Override the ceilings with `SIGNALDASH_MESSAGE_ATTACHMENT_MAX_BYTES` and
+`SIGNALDASH_MESSAGE_ATTACHMENT_MAX_TOTAL_BYTES`; raising either also needs
+`SIGNALDASH_MESSAGE_SEND_MAX_BODY_BYTES` raised to match, because base64 costs a
+third on top of the bytes and a body over that cap is refused with
+`413 request_too_large` before it is parsed.
+
+Future LinkedIn posts are persisted by the backend only after the exact text,
+offset-qualified publish time, mentions, image attachments, and optional first
+comment have human approval. The stored image bytes and comment text cannot
+drift after approval. The scheduler publishes the comment through the same
+connected LinkedIn account immediately after the post. It persists the post ID
+before attempting the comment, so a comment failure never republishes the post.
+The scheduler
+uses the same sender binding, action ledger, duplicate guard, daily budget, and
+provider-warning lock as immediate publishing. An interrupted or ambiguous
+execution fails closed and is never retried automatically.
+
+`sd_schedule_message` puts one exact message into one exact chat at one exact
+time, on WhatsApp or LinkedIn, text only. It enqueues; it never sends. The
+attachment bytes a WhatsApp send accepts are refused here rather than held on
+disk for days. The worker sends,
+through `sendWhatsAppMessage` and through the LinkedIn preflight and write path,
+so a scheduled message clears every guard a live send clears, including the
+daily budget and the duplicate guard, at the moment it fires rather than at the
+moment it was written. Scheduling is refused with
+`428 read_before_send_required` unless this session has already read that exact
+chat, at `limit` 10 or more on LinkedIn, because the row has to carry a hash of
+the conversation it was written against. That hash is read from the recorded
+read and cannot be supplied by the caller: `watermark` and `item_limit` are
+refused by name rather than accepted and overwritten, since a caller that
+believes it set them believes something false. At fire time the worker re-reads
+the thread and compares. Anything other than "unchanged" parks the row in
+`needs_review` with a reason and sends nothing, because a conversation that
+moved is a question for a human and not a failure of the message.
+`sd_scheduled_messages` lists the caller's own rows with those reasons, and
+counts the `needs_review` ones outside whatever filter was asked for, so a
+filtered listing cannot hide a message waiting on a person.
+`sd_cancel_scheduled_message` cancels a row that has not fired.
+A row belonging to another account is refused in exactly the same words as an id
+that never existed, so the refusal cannot be used to prove somebody else's
+message is real. A row that already sent is refused with the plain statement
+that cancelling cannot unsend it.
+
+A campaign is one connection request per approved person, then the approved
+message once a fresh profile read proves that person accepted, then an optional
+follow-up that stops the moment they reply. A pending invitation that merely
+disappeared is never treated as an acceptance. Campaign writes consume the same
+per-sender daily budget as manual sends, obey the Monday-Friday 09:00-17:00
+sender-local window and the 90-180 second pacing interval, and cannot start
+without a human approval recorded on the authenticated approval page. An agent
+can present that page and carry back the one-time code it mints, but can never
+approve on its own.
+
+A withdrawal sweep clears a backlog of old pending SENT invitations. It uses the
+same object as an invitation batch with the arrow reversed: freeze the exact
+invitation ids now, one human approval bound to the rendered view, then one
+withdrawal per tick. Two things it will never claim, because both contradict
+LinkedIn's own documentation: withdrawing does **not** lift an active sending
+restriction, so this buys no sending capacity; and after withdrawing, that
+member cannot be re-invited for up to three weeks. The exclusion list is a
+required field rather than an option, so protecting nobody is a deliberate
+choice and not a default. LinkedIn exposes invitation age as a bucket ("sent 4
+months ago"), never a date, so the filter selects only when the whole bucket
+clears the threshold and the review page reports what that conservatism held
+back. The sweep runs on its own daily allowance and never consumes the send
+budget, and any 403, 429, provider warning, or account status change stops it
+entirely.
+
 LinkedIn invitation auto-accept is off for every user until that user
 explicitly enables it with `confirm:true`. The optional filters are an exact
 public-identifier allowlist and description-keyword matches; when both groups
@@ -201,6 +350,15 @@ workflow around that runtime control:
   `resets_at`, plus matching `X-RateLimit-*` headers. When the per-user cap is
   exhausted, SignalDash returns HTTP 429 with `code: "rate_limit_exceeded"` and
   `Retry-After`. Usage is persisted server-side and resets at midnight UTC.
+- The caps are per channel lane: LinkedIn actions, WhatsApp and email sends
+  together, and message deletes each spend their own daily budget. A `429` names
+  the cap it hit; it is never a statement about another lane. Two caveats worth
+  knowing: on the day a deployment first upgrades past the lane split, that
+  day's existing count is still read on the LinkedIn side (it is ambiguous, and
+  the conservative reading is the safe one) and clears at the next UTC midnight;
+  and the WhatsApp/email lane is keyed per access token while the LinkedIn
+  ledger is keyed per user, so several live tokens for one user get one LinkedIn
+  budget but a WhatsApp budget each.
 - Read the exact thread before every send.
 - Preview an exact invitation target and note before sending it.
 - List the exact received or sent invitation before accepting or withdrawing it.
@@ -234,6 +392,68 @@ write reservation. Downtime never creates a catch-up burst. Future start
 dates, recurring schedules, automatic follow-ups, acceptance-triggered
 messages, and multi-message sequences are not exposed.
 
+Deleting a WhatsApp message is a write, and an irreversible one, so it is
+treated as such. SignalDash proves the chat belongs to the connected account,
+proves the message sits in that exact chat, and proves the account wrote it,
+before anything is removed; someone else's message is refused with `403
+message_not_own`. Every attempt is appended to that user's own durable audit
+trail with the chat, the message, the outcome and the timestamp, including the
+attempts that fail and the ones whose outcome the network left unknown. A
+delete already recorded for the same chat and message is refused with `409
+duplicate_delete` rather than replayed. Deletes spend a separate daily budget
+(`SIGNALDASH_DAILY_DELETE_LIMIT`, default 200) so a cleanup can never consume
+the sending capacity it exists to repair. `wa_delete_messages` runs at most 200
+entries strictly one at a time, pauses `SIGNALDASH_WA_DELETE_PACE_MS` between
+them, and stops at `SIGNALDASH_WA_DELETE_BATCH_DEADLINE_MS`, returning the
+untouched remainder as `skipped` with `code: batch_deadline` so the caller can
+resume exactly those. WhatsApp applies its own time and role limits to deleting
+for everyone and can answer successfully without removing anything, so re-read
+the chat to confirm.
+
+## Releasing
+
+A release is a tag push. `.github/workflows/release.yml` runs `./release.sh` on
+the AX41 self-hosted runner, and that script is the same one a laptop runs, so
+there is no second code path to keep honest:
+
+```bash
+git tag v0.28.0 && git push origin v0.28.0
+```
+
+`release.sh` refuses to publish if the packed files have uncommitted changes or
+if the version in `package.json` is already on the registry, then runs the
+syntax check, the tests, `npm pack`, and the prepublish smoke gate against the
+tarball it just built. That gate installs the tarball into a scratch HOME and
+drives the real CLI, so a package that unpacks but cannot run never ships. Any
+other branch or a `workflow_dispatch` run does all of that and stops one command
+short, at `./release.sh --dry-run`.
+
+**The credential is the `NPM_TOKEN` secret**, an npm granular access token
+scoped to `@floomhq/signaldash` with write access:
+
+```bash
+gh secret set NPM_TOKEN -R floomhq/signaldash
+```
+
+Trusted publishing (OIDC) is not an option here, so do not spend time on it:
+npm does not accept self-hosted runners yet, and this repo is on a self-hosted
+runner because GitHub-hosted minutes are unavailable. The workflow asks the
+registry directly on every run (`scripts/oidc-check.mjs`) and prints the answer,
+because npm's own OIDC helper is written never to throw and turns a refusal into
+an ordinary auth error.
+
+To exercise the publish itself without touching npmjs, run it against a
+throwaway registry:
+
+```bash
+scripts/publish-rehearsal.sh
+```
+
+That starts verdaccio in a container, mints an account on it, and runs the real
+`./release.sh` with no `--dry-run`, then prints what the registry received. It
+is the only way to test the publish command and the tarball a client actually
+downloads before a version number is spent.
+
 ## Development
 
 ```bash
@@ -241,3 +461,33 @@ npm test
 npm run check
 npm pack --dry-run
 ```
+
+`wa_transcribe_voice` runs on the SignalDash host and has two backends. The
+default, `gemini`, sends the audio to Vertex AI using that host's own
+credentials; it is the one that survives German speech with English technical
+terms mixed into it, and being network-bound it does not compete with the
+gateway for CPU. The fallback, `whisper`, needs `python3` with `faster-whisper`
+installed on the host and runs the `small` CPU int8 model, which is much weaker
+on that kind of code-switching. Every response therefore names the engine that
+produced the text in `backend`, and a `gemini` request that had to fall back
+also explains why in `fallback_reason`.
+
+Pick the engine per request with the optional `backend` argument (`gemini` or
+`whisper`), or set the default with `SIGNALDASH_TRANSCRIBE_BACKEND`. Override
+the rest with `SIGNALDASH_TRANSCRIBE_PYTHON`, `SIGNALDASH_TRANSCRIBE_MODEL`
+(local model), `SIGNALDASH_TRANSCRIBE_GEMINI_MODEL`,
+`SIGNALDASH_TRANSCRIBE_GEMINI_PROJECT`,
+`SIGNALDASH_TRANSCRIBE_GEMINI_LOCATION`,
+`SIGNALDASH_TRANSCRIBE_GEMINI_TIMEOUT_S` (total budget for the Vertex call
+including retries, default 240s, and it has to stay under
+`SIGNALDASH_TRANSCRIBE_TIMEOUT_MS`, default 420000, so the local fallback still
+fits underneath), `SIGNALDASH_TRANSCRIBE_GEMINI_MAX_BYTES`,
+`SIGNALDASH_TRANSCRIBE_GEMINI_MAX_OUTPUT_TOKENS`, or
+`SIGNALDASH_ATTACHMENT_MAX_BYTES`.
+
+The Gemini backend authenticates with the credentials already on the host: the
+audio never leaves it with a SignalDash key attached, and the transcriber
+resolves those credentials itself, in the child process, from the file named by
+`SIGNALDASH_TRANSCRIBE_AWS_ENV_FILE`. The gateway process forwards only
+configuration, never a secret. That backend reports `language` as `null`: it is
+asked for the transcript text and nothing else.