@floomhq/signaldash 0.13.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.
 
@@ -106,20 +111,176 @@ SignalDash exposes:
 - `li_list_chats`
 - `li_read_messages(chat_id)`
 - `li_send_message(chat_id, text)`
+- `li_send_invitation(provider_id, note?, confirm?)`
+- `li_invitations_received(limit?, cursor?)`
+- `li_accept_invitation(invitation_id, confirm)`
+- `li_invitations_sent(limit?, cursor?)`
+- `li_withdraw_invitation(invitation_id, confirm)`
+- `sd_contact_state(channel, identifiers, action?, reason?, confirm?)`
+- `sd_budget_status()`
+- `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
+are configured, both must match. The single backend worker reads one bounded
+received-invitation page, accepts at most five invitations per run and ten per
+UTC day by default, jitters every action, and also consumes the shared daily
+LinkedIn action budget. Three consecutive parse or provider errors disable the
+setting. `sd_auto_accept_status` exposes accepted counts today and this week,
+failed attempts today, remaining capacity, the stop reason, and sanitized
+records for invitations whose provider shape could not be parsed. Both the current nested
+`specifics.shared_secret` and legacy top-level shape are supported; secrets are
+never returned or logged.
+
+`li_search_connections` is the zero-cost, zero-provider-risk list-building
+path. It searches only the authenticated user's stored connection snapshot by
+name, headline, or company, supports company/headline-keyword/date filters, and
+joins exact local contact state. It never calls LinkedIn, Unipile, or a paid
+discovery API. When no snapshot exists, it points to the paced sync below
+without starting provider work.
+
+`li_discover_people` is the capped paid fallback for people beyond a completed
+stored network. SignalDash runs the same role/company intent against the local
+snapshot first and returns local matches without spending. With no local
+matches, the first call returns an exact paid preview. An identical
+`confirm:true` call can make one serialized HarvestAPI profile-search request.
+That reservation consumes the preview atomically, so every later paid request
+requires a fresh preview and approval.
+Durable per-user pacing, per-user and tenant request caps, and a tenant-wide
+micro-dollar cap are reserved atomically before the request. Hidden cards,
+malformed identities, exact stored connections, and exact contact-state rows
+already marked connected are excluded. Results are read-only planning evidence
+and cannot become invitation-batch targets automatically.
+
+Invitation batches are the narrow executable campaign boundary. An agent turns
+the human's request into 1–10 exact canonical LinkedIn Classic profile URLs,
+inclusion reasons, and optional notes, then creates an immutable durable
+preview. The agent can inspect or cancel the batch but cannot approve it. A
+human opens the returned absolute review URL, reauthenticates with the SignalDash
+invite credential, selects unchecked eligible targets, and approves the exact
+stored payload for up to 24 hours. Five failed credential attempts block that
+batch's authentication surface for 15 minutes. The single backend worker
+rechecks sender binding, exact identity, contact state, prior actions, chats,
+invitations, daily/weekly budgets, weekday work window, pacing, and the tenant
+breaker before each at-most-once write. A tenant provider-authentication
+failure opens the persisted breaker immediately; an open breaker rejects new
+batches and stops queued preview work before provider reads.
+
+This is not a general campaign engine. It has no pause/resume, priority,
+future start, recurring schedule, acceptance polling, automatic message,
+follow-up, discovery-to-send bridge, or runtime target/text generation.
+
 The CLI also provides a paced, resumable LinkedIn connections export:
 
 ```bash
@@ -135,17 +296,65 @@ 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.
 - Email sends accept one recipient at a time and require a recent
   `email_read` containing that address.
 - Never infer a recipient from a partial name.
 - Never send a duplicate or retry an ambiguous timeout without re-reading.
+- Invitation auto-accept remains off until explicitly enabled, consumes both
+  its dedicated daily cap and the shared LinkedIn action cap, and disables
+  itself after three consecutive parse or provider errors.
 - Do not parallelize sends or work around a rate limit.
+- Do not bypass paid-discovery previews, pacing, request caps, or cost caps.
 - Stop on a provider warning, checkpoint, restriction, HTTP 403, or HTTP 429.
 - Avoid bulk profile reads, copied message bursts, cold-account automation,
   and unsolicited WhatsApp messaging.
 
-SignalDash exposes no LinkedIn invitation tool.
+LinkedIn invitation writes are single-object actions. SignalDash serializes
+them with other LinkedIn writes, requires an exact preview or list read,
+applies the shared daily action cap, and enforces a separate 100-attempt weekly
+policy by default. For a new invitation, jitter completes before the final
+preflight and action reservation; that preflight verifies relationship state,
+pending invitations in both directions, and absence of an existing one-to-one
+chat. Provider timeouts become non-retryable `outcome_unknown` locks.
+
+The first campaign time boundary is intentionally narrower than scheduled
+messaging. Campaign invitations require a valid sender IANA timezone, run only
+Monday through Friday from 09:00 to 17:00 sender-local time, and reserve a new
+90–180 second per-sender pacing interval atomically with every attempted
+action. Timing is checked before final provider preflight and again during the
+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
 
@@ -154,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.