@floomhq/signaldash 0.22.0 → 0.27.0

package/README.md

@@ -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.27.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,115 @@ 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)`
 
 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 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.
+
+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 +296,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 +338,24 @@ 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.
+
 ## Development
 
 ```bash
@@ -241,3 +363,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.