@floomhq/signaldash 0.22.0 → 0.28.0

package/bin/sd.mjs

@@ -11,6 +11,7 @@ import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { readConfigFile, updateConfigFile } from "../lib/config-file.js";
+import { renderSkillTemplate } from "../lib/skill-template.cjs";
 
 // Lazy-load presentation deps so `mcp` (stdio, machine-facing) stays clean/fast.
 async function ui() {
@@ -20,6 +21,25 @@ async function ui() {
 }
 
 const DEFAULT_BACKEND = process.env.SIGNALDASH_BACKEND || "https://signaldash-api.floom.dev";
+// The shape of an invite code, deliberately a hand-kept copy of
+// INVITE_CODE_SHAPE in server/server.cjs rather than an import: server/ is
+// not in package.json's "files" allowlist, so it never ships in the
+// published npm tarball and bin/sd.mjs cannot depend on it at runtime. Two
+// copies of this shape can therefore never be textually merged into one;
+// test/invite-code-shortening.test.js requires server.cjs (test-only, not
+// shipped) to assert the CLI still accepts every code the live server
+// actually issues, which is the guarantee that matters here.
+//
+// The floor here (8 hex chars) is intentionally HIGHER than the server's
+// own floor (6): the server keeps 6 low for backward compatibility with
+// already-issued short codes it must still honor, but 6 hex chars is only
+// 24 bits of entropy for a value an attacker can brute-force against the
+// login endpoint, so the CLI does not need to (and should not) accept
+// anything shorter than the 32-bit floor this project has always minted
+// against. Every code production has ever issued is 10+ hex chars, or the
+// sd-XXXX-XXXX form below; the shape census is in
+// test/invite-code-shortening.test.js.
+export const INVITE_CODE_REGEX = /^(?:[0-9a-f]{8,32}|sd-[0-9a-f]{4}-[0-9a-f]{4})$/i;
 const PACKAGE_VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 ).version;
@@ -87,13 +107,18 @@ export async function cmdLogin(code, backend, dependencies = {}) {
     { auth: false, backend: targetBackend },
   );
   if (r.status !== 200) {
+    // Previously any error whose text loosely matched /used|invalid|unknown/i
+    // was swallowed into "you are already set up" whenever a local token
+    // existed. That was never precise: the server's /login route treats a
+    // revoked code exactly like an unknown one on purpose (same 403, see
+    // server.cjs, so an attacker can't tell them apart), and it does NOT
+    // reject a code that was already redeemed -- re-running `login` with the
+    // SAME valid code succeeds with a fresh 200 token, it never reaches this
+    // branch. So a 403/other error here, even with a local token present,
+    // means the code just typed is wrong, expired, or revoked -- never "you
+    // already did this". Report it honestly instead of masking it as success.
     const msg = String(r.json.error || r.status);
-    if (/used|invalid/i.test(msg) && loadCfg().token) {
-      log("You are already set up on this machine. Run `signaldash status` to see what is connected.");
-      return;
-    }
     error("login failed:", msg);
-    if (/used/i.test(msg)) error("Invite codes are single-use. If you already ran this, try: signaldash status");
     process.exitCode = 1; return;
   }
   updateCfg(current => ({
@@ -106,6 +131,46 @@ export async function cmdLogin(code, backend, dependencies = {}) {
   log("machine, and are never exposed to your agent. Only you can see your data.");
 }
 
+// Store a session token you already hold. The /i/<code> page used to print
+// one as the final step of web onboarding and this command did not exist, so
+// people hit "unknown command" at the one point where they wire up their
+// agent. That page no longer hands out tokens at all (reopening it would have
+// traded a leaked invite code for someone else's live session), so the normal
+// way in is `login <code>`. This stays for a token handed over out of band.
+export async function cmdLoginToken(token, backend, dependencies = {}) {
+  const request = dependencies.request || api;
+  const log = dependencies.log || console.log;
+  const error = dependencies.error || console.error;
+  if (!token) {
+    error("usage: signaldash login-token <token>");
+    process.exitCode = 1; return;
+  }
+  const targetBackend = backend || loadCfg().backend || DEFAULT_BACKEND;
+  // Verify before persisting. A mistyped or expired token written to disk would
+  // fail later as a confusing "not connected" on every command instead of here.
+  const probe = await request(
+    "/connect/whatsapp/status",
+    undefined,
+    { method: "GET", backend: targetBackend, token },
+  );
+  if (probe.status === 401 || probe.status === 403) {
+    error("login failed: that token is not valid. It may have expired, or a newer login replaced it.");
+    process.exitCode = 1; return;
+  }
+  if (probe.status >= 400) {
+    error("login failed:", probe.json.error || probe.status);
+    process.exitCode = 1; return;
+  }
+  updateCfg(current => ({
+    ...current,
+    backend: targetBackend,
+    token,
+  }));
+  log(`Logged in to SignalDash (${targetBackend}).`);
+  log("Your LinkedIn/WhatsApp/email credentials live on that server, not on this");
+  log("machine, and are never exposed to your agent. Only you can see your data.");
+}
+
 export async function cmdLogout(dependencies = {}) {
   const request = dependencies.request || api;
   const log = dependencies.log || console.log;
@@ -214,9 +279,52 @@ export async function cmdClaim(provider, accountId, dependencies = {}) {
 
 // ---- MCP (stdio). Every tool proxies through the backend with the token. ----
 const TOOLS = [
-  { name: "li_list_chats", ch: "li", action: "list_chats", description: "List your LinkedIn chats." },
-  { name: "li_read_messages", ch: "li", action: "read", description: "Read messages in a LinkedIn chat. args: chat_id" },
-  { name: "li_send_message", ch: "li", action: "send", description: "Send a LinkedIn message (rate-safe). args: chat_id, text" },
+  {
+    name: "li_list_chats",
+    ch: "li",
+    action: "list_chats",
+    description: "List or search your LinkedIn chats. `search` filters on identifiers, never on a person name (a 1:1 chat has no name); the response reports how far it scanned.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 100, description: "How many chats to return. With `search`, how many MATCHES to return." },
+        cursor: { type: "string", maxLength: 4000, description: "Continue from a previous page or a previous search." },
+        search: { type: "string", minLength: 1, maxLength: 200, description: "Filter chats on name and counterpart identifiers. The provider cannot filter a chat list, so SignalDash filters over a bounded scan and the response reports `scanned_chats` and `exhaustive` so a miss is never mistaken for a proven absence. A 1:1 chat has no name, so search by identifier or phone number, not by person name." },
+        max_scan: { type: "integer", minimum: 1, maximum: 500, description: "How many chats the search may scan before it stops and reports exhaustive:false. Default 200, and never more than five provider pages: bulk reading is the top account-restriction trigger, so go deeper with the returned cursor rather than with a bigger scan." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_read_messages",
+    ch: "li",
+    action: "read",
+    description: "Read messages in a LinkedIn chat. args: chat_id",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+      },
+      required: ["chat_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_send_message",
+    ch: "li",
+    action: "send",
+    description: "Send a LinkedIn message (rate-safe). args: chat_id, text",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        text: { type: "string", minLength: 1, maxLength: 5000 },
+      },
+      required: ["chat_id", "text"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "li_send_invitation",
     path: "/li/send_invitation",
@@ -411,6 +519,20 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "sd_voice_profile",
+    path: "/sd/voice/profile",
+    description: "Build or fetch this user's personal writing-voice profile for one channel, mined ONLY from up to ~50 of their own SENT messages on that channel (never the other side of any conversation, never another user's data). Returns compact markdown: hard length stats (median/p75/p90 characters), 5-10 verbatim redacted exemplars, negative constraints, and language behavior. Computed once and cached; call with force_recompute:true only when explicitly asked to refresh. Call this before drafting on the user's behalf and match the returned stats and exemplars.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channel: { type: "string", enum: ["linkedin", "whatsapp", "email"] },
+        force_recompute: { type: "boolean", default: false },
+      },
+      required: ["channel"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "li_search_connections",
     path: "/li/connections/search",
@@ -556,16 +678,448 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
-  { name: "wa_list_chats", ch: "wa", action: "list_chats", description: "List your WhatsApp chats." },
-  { name: "wa_read_messages", ch: "wa", action: "read", description: "Read messages in a WhatsApp chat. args: chat_id" },
-  { name: "wa_send_message", ch: "wa", action: "send", description: "Send a WhatsApp message (rate-safe). args: chat_id, text" },
+  {
+    name: "sd_campaign_create",
+    path: "/sd/campaign/create",
+    description: "Create one campaign: a paced connection request to each exact person, then the exact approved message(s) once that person is PROVEN to have accepted, then an optional follow-up that stops the moment they reply. Nothing is sent until a human approves this exact recipient list and this exact message text on the approval page. Targets come from an explicit list you supply (for example one you built with li_search_connections or li_post_reactions) or from your own post engagers, which costs zero profile fetches. If the user already sent someone a connection request by hand and just wants the follow-up automated, set adopt_existing_invitation on that target instead of leaving them out. Draft the messages in the user's own voice and keep them short: the on-acceptance group is 2-3 separate short sends, never one block.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_label: { type: "string", minLength: 1, maxLength: 120 },
+        time_zone: {
+          type: "string",
+          minLength: 1,
+          description: "Sender IANA timezone. Execution is Mon-Fri 09:00-17:00 sender-local.",
+        },
+        target_source: {
+          type: "string",
+          enum: ["explicit", "post_engagers"],
+          default: "explicit",
+        },
+        targets: {
+          type: "array",
+          minItems: 1,
+          maxItems: 150,
+          description: "Explicit targets. Each needs a canonical linkedin.com/in/ URL or an exact provider_id.",
+          items: {
+            type: "object",
+            properties: {
+              profile_url: { type: "string", format: "uri" },
+              provider_id: { type: "string", minLength: 5, maxLength: 500 },
+              inclusion_reason: { type: "string", minLength: 1, maxLength: 240 },
+              note: {
+                type: "string",
+                maxLength: 200,
+                description: "Optional invitation note.",
+              },
+              display_name: { type: "string", maxLength: 160 },
+              headline: { type: "string", maxLength: 300 },
+              adopt_existing_invitation: {
+                type: "boolean",
+                default: false,
+                description: "Set true ONLY when the user already sent this exact person a connection request by hand and now wants the follow-up automated. SignalDash then REQUIRES a still-pending sent invitation to that person and sends none of its own: it adopts the existing one, watches for acceptance, and runs the message sequence. If no pending invitation is found the person is dropped, never invited. Incompatible with note, because no invitation goes out.",
+              },
+            },
+            required: ["inclusion_reason"],
+            additionalProperties: false,
+          },
+        },
+        engagers: {
+          type: "object",
+          description: "Only with target_source post_engagers. The server reads your own recent posts and their reactions and comments, which return member id and network distance directly, so no profiles are fetched.",
+          properties: {
+            post_limit: { type: "integer", minimum: 1, maximum: 10, default: 5 },
+            max_targets: { type: "integer", minimum: 1, maximum: 150, default: 50 },
+            inclusion_reason: { type: "string", minLength: 1, maxLength: 240 },
+            note: { type: "string", maxLength: 200 },
+          },
+          additionalProperties: false,
+        },
+        messages: {
+          type: "array",
+          minItems: 1,
+          maxItems: 5,
+          description: "The exact frozen texts. after_days 0 means sent once the invitation is accepted (1-3 of these, sent as separate consecutive messages); a later step needs after_days 1-30 and only goes out if there has been no reply.",
+          items: {
+            type: "object",
+            properties: {
+              text: { type: "string", minLength: 1, maxLength: 1200 },
+              after_days: { type: "integer", minimum: 0, maximum: 30 },
+            },
+            required: ["text"],
+            additionalProperties: false,
+          },
+        },
+        invite_ttl_days: {
+          type: "integer",
+          minimum: 1,
+          maximum: 60,
+          default: 21,
+          description: "An invitation not accepted within this many days is dropped and never messaged.",
+        },
+      },
+      required: ["source_label", "time_zone", "messages"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_campaign_preview",
+    path: "/sd/campaign/preview",
+    description: "Inspect one campaign before approval: every exact recipient, every exclusion and its reason, the exact message text for each step, the timing, the shared daily budget, and the approval_url to send the human. Show the human this content. This read also authorizes a later exact cancel. An agent cannot approve a campaign; only the authenticated human page can, and it can hand you a one-time code for sd_campaign_approve.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        campaign_id: { type: "string", minLength: 36, maxLength: 36 },
+      },
+      required: ["campaign_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_campaign_approve",
+    path: "/sd/campaign/approve",
+    description: "Record the human's approval of one campaign using the one-time code they generated on the authenticated approval page. You cannot create that code, guess it, or approve without it, and it only ever approves the exact payload and exact recipients they reviewed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        campaign_id: { type: "string", minLength: 36, maxLength: 36 },
+        confirm_token: {
+          type: "string",
+          pattern: "^sd-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}$",
+          description: "The code the human read off the approval page.",
+        },
+      },
+      required: ["campaign_id", "confirm_token"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_campaign_status",
+    path: "/sd/campaign/status",
+    description: "Monitor one campaign: invited, acceptance proven, messaged, replied and halted, expired, or excluded per person, plus every message step and any provider response SignalDash could not parse.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        campaign_id: { type: "string", minLength: 36, maxLength: 36 },
+      },
+      required: ["campaign_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_campaign_cancel",
+    path: "/sd/campaign/cancel",
+    description: "Revoke the human approval and cancel one freshly inspected campaign. Stops every unsent invitation and every unsent message. Cannot recall an executing write. Restarting requires a new preview and a new human approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        campaign_id: { type: "string", minLength: 36, maxLength: 36 },
+        approval_view_hash: {
+          type: ["string", "null"],
+          pattern: "^[0-9a-f]{64}$",
+        },
+        confirm: { type: "boolean" },
+      },
+      required: ["campaign_id", "approval_view_hash", "confirm"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_withdrawal_batch_create",
+    path: "/li/withdrawal_batch/create",
+    description:
+      "Clear a backlog of old PENDING SENT LinkedIn invitations. Freezes the exact invitation ids matching an age rule, then one human approval withdraws them one at a time. Two things you must tell the user, because both are LinkedIn's own documented behaviour: (1) this does NOT free up sending capacity, withdrawing does not lift an active sending restriction, it only clears a stale backlog; (2) after withdrawing you cannot re-invite that person for UP TO THREE WEEKS. `exclude` is REQUIRED, not optional: ask the user who must NOT be withdrawn before you call this, because a blanket age rule will otherwise catch people they wanted to keep pending. Passing an empty array is allowed but it means nobody is protected. Age labels are buckets ('sent 4 months ago'), not dates, so the filter is bucket-accurate at best and deliberately holds back anyone whose bucket straddles the threshold.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        account: {
+          type: "string",
+          enum: ["linkedin"],
+          description: "Only LinkedIn sent invitations can be swept.",
+        },
+        older_than_days: {
+          type: "integer",
+          minimum: 30,
+          maximum: 3650,
+          default: 90,
+          description:
+            "Withdraw invitations older than this. Bucket-accurate at best. Minimum 30.",
+        },
+        exclude: {
+          type: "array",
+          maxItems: 100,
+          description:
+            "REQUIRED. People to protect from the sweep, matched exactly, never fuzzily. Ask the user for these by name before calling. An empty array means nobody is protected.",
+          items: {
+            type: "object",
+            properties: {
+              kind: {
+                type: "string",
+                enum: [
+                  "invitation_id",
+                  "provider_id",
+                  "public_identifier",
+                  "profile_url",
+                  "member_urn",
+                  "display_name",
+                ],
+              },
+              value: { type: "string", minLength: 1, maxLength: 1000 },
+            },
+            required: ["kind", "value"],
+            additionalProperties: false,
+          },
+        },
+        time_zone: {
+          type: "string",
+          minLength: 1,
+          maxLength: 64,
+          description:
+            "IANA sender timezone. Withdrawals only run Monday-Friday 09:00-17:00 in this zone.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 1500,
+          description: "Optional ceiling on how many to withdraw.",
+        },
+        source_label: { type: "string", minLength: 1, maxLength: 120 },
+        allow_unmatched_exclusions: {
+          type: "boolean",
+          description:
+            "By default an exclusion that matches nobody fails the preview, because that is what a typo looks like and a typo means the protected person gets withdrawn. Set true only when the user confirms the mismatch is expected.",
+        },
+      },
+      required: ["account", "exclude", "time_zone"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_withdrawal_batch_status",
+    path: "/li/withdrawal_batch/status",
+    description:
+      "Inspect or monitor one withdrawal sweep: how many are done and remaining, the per-day pace and this sweep's own daily allowance (it never consumes your send budget), the stop reason if it stopped, any provider response SignalDash could not parse, the exact people your exclusions protected, and the approval_url to send the human. This read also authorizes a later exact cancel.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        withdrawal_batch_id: { type: "string", minLength: 36, maxLength: 36 },
+      },
+      required: ["withdrawal_batch_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_withdrawal_batch_approve",
+    path: "/li/withdrawal_batch/approve",
+    description:
+      "Record the human's approval of one withdrawal sweep using the one-time code they generated on the authenticated approval page. You cannot create that code, guess it, or approve without it, and it only ever approves the exact invitations they left ticked.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        withdrawal_batch_id: { type: "string", minLength: 36, maxLength: 36 },
+        confirm_token: {
+          type: "string",
+          pattern: "^sd-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}$",
+          description: "The code the human read off the approval page.",
+        },
+      },
+      required: ["withdrawal_batch_id", "confirm_token"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_withdrawal_batch_cancel",
+    path: "/li/withdrawal_batch/cancel",
+    description:
+      "Revoke the human approval and stop one freshly inspected withdrawal sweep. Stops every withdrawal that has not started. Cannot recall one already submitted, and cannot restore the three-week re-invite block for people already withdrawn.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        withdrawal_batch_id: { type: "string", minLength: 36, maxLength: 36 },
+        approval_view_hash: {
+          type: ["string", "null"],
+          pattern: "^[0-9a-f]{64}$",
+        },
+        confirm: { type: "boolean" },
+      },
+      required: ["withdrawal_batch_id", "approval_view_hash", "confirm"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "wa_list_chats",
+    ch: "wa",
+    action: "list_chats",
+    description: "List or search your WhatsApp chats. `search` matches the phone number (chats carry it as attendee_public_identifier), not a person name; the response reports how far it scanned.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 100, description: "How many chats to return. With `search`, how many MATCHES to return." },
+        cursor: { type: "string", maxLength: 4000, description: "Continue from a previous page or a previous search." },
+        search: { type: "string", minLength: 1, maxLength: 200, description: "Filter chats on name and counterpart identifiers. The provider cannot filter a chat list, so SignalDash filters over a bounded scan and the response reports `scanned_chats` and `exhaustive` so a miss is never mistaken for a proven absence. A 1:1 chat has no name, so search by identifier or phone number, not by person name." },
+        max_scan: { type: "integer", minimum: 1, maximum: 500, description: "How many chats the search may scan before it stops and reports exhaustive:false. Default 200, and never more than five provider pages: bulk reading is the top account-restriction trigger, so go deeper with the returned cursor rather than with a bigger scan." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "wa_read_messages",
+    ch: "wa",
+    action: "read",
+    description: "Read messages in a WhatsApp chat. args: chat_id",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+      },
+      required: ["chat_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "wa_get_attachment",
+    path: "/wa/get_attachment",
+    description: "Download one attachment of one WhatsApp message this account owns and store it on the SignalDash host. Read the chat first to obtain the exact message_id and attachment_id. Returns the stored path, mimetype, byte size and sha256.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        message_id: { type: "string", minLength: 1, maxLength: 500 },
+        attachment_id: { type: "string", minLength: 1, maxLength: 500 },
+      },
+      required: ["chat_id", "message_id", "attachment_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "wa_transcribe_voice",
+    path: "/wa/transcribe_voice",
+    description: "Transcribe one WhatsApp voice note or audio attachment this account owns. Fetches the audio through SignalDash, transcribes it on the SignalDash host, and returns the transcript text, the stored audio path, and the `backend` that produced the text. Optional `backend` picks the engine: `gemini` (default, accurate on German with English terms mixed in) or `whisper` (local small model, much weaker on code-switching). A `gemini` request that cannot reach Gemini falls back to the local model and says so in `backend` and `fallback_reason`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        message_id: { type: "string", minLength: 1, maxLength: 500 },
+        attachment_id: { type: "string", minLength: 1, maxLength: 500 },
+        backend: { type: "string", enum: ["gemini", "whisper"] },
+      },
+      required: ["chat_id", "message_id", "attachment_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "wa_send_message",
+    ch: "wa",
+    action: "send",
+    description: "Send a WhatsApp message (rate-safe). args: chat_id, text, attachments. Read the chat first: a send into a thread this account has not read recently is refused. The send re-reads the thread immediately before sending and refuses with `409 thread_changed` if the conversation moved after that read, because a draft written against the old thread may now be deaf or wrong; re-read, revise, and send again. A re-read that fails is `502 thread_preflight_unavailable` and nothing was sent. `attachments` optionally carries up to 4 base64 files as exact {filename, content_type, content_base64} objects, at most 16 MiB per file and 16 MiB per message, and accepts images, 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. An attachment send is rate-limited, deduplicated and recorded exactly like a text send, and spends the same daily budget. If a send times out or the provider never confirms it, the message may still have been delivered: SignalDash records it and refuses an identical retry with `409 send_outcome_unknown`. Read the chat, and only if the message is genuinely absent, resend the identical payload with `confirm_resend:true`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        text: { type: "string", minLength: 1, maxLength: 5000 },
+        attachments: {
+          type: "array", maxItems: 4,
+          items: {
+            type: "object",
+            properties: {
+              filename: { type: "string", minLength: 1, maxLength: 180 },
+              content_type: {
+                type: "string",
+                enum: [
+                  "image/png",
+                  "image/jpeg",
+                  "image/webp",
+                  "image/gif",
+                  "application/pdf",
+                  "text/csv",
+                  "text/plain",
+                  "application/json",
+                  "application/zip",
+                  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                ],
+              },
+              content_base64: { type: "string", minLength: 1 },
+            },
+            required: ["filename", "content_type", "content_base64"],
+          },
+        },
+        confirm_resend: { type: "boolean", const: true },
+      },
+      // `text` alone is no longer required: a document with no caption is a
+      // legitimate message.
+      //
+      // Die Regel stand hier bis zum 11.08. als `anyOf` auf oberster Ebene.
+      // Das hat das Werkzeug bei einem Client gekostet, der Schemata lokal
+      // kompiliert: er hat es kommentarlos aus seiner Liste geworfen. Ueber
+      // Tage war wa_send_message das EINZIGE der 45 Werkzeuge, das dort fehlte,
+      // und zugleich das einzige mit einem top-level anyOf. Der Server hat es
+      // die ganze Zeit ausgeliefert.
+      //
+      // Die Regel geht dadurch nicht verloren: das Backend weist einen Aufruf
+      // ohne Text und ohne Anhang ohnehin ab, unabhaengig davon, ob ein Client
+      // vorher geprueft hat. Sie steht in der Beschreibung, wo jeder Client sie
+      // lesen kann, statt in einem Konstrukt, an dem einer von ihnen erstickt.
+      required: ["chat_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "wa_delete_message",
+    path: "/wa/delete_message",
+    description: "Delete one WhatsApp message this account SENT, in a chat this account owns. Read the chat first: the exact `message_id` comes from `wa_read_messages`. Only your own messages can be deleted; someone else's is refused with `403 message_not_own`. This is irreversible and is never retried: a delete already recorded for this exact chat and message is refused with `409 duplicate_delete` rather than replayed. WhatsApp applies its own time and role limits to deleting for everyone and can answer successfully without removing anything, so re-read the chat afterwards to confirm. Deletes spend their own daily budget and never consume your send budget.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        message_id: { type: "string", minLength: 1, maxLength: 500 },
+      },
+      required: ["chat_id", "message_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "wa_delete_messages",
+    path: "/wa/delete_messages",
+    description: "Delete several WhatsApp messages this account sent, at most 200 per call. Every entry runs the exact same ownership, budget and audit path as `wa_delete_message`, one at a time with a pause between them, never in parallel. Returns a per-entry `ok` with the refusal `code` and `error` for each one that did not go through, so a partial result is readable rather than all-or-nothing. Entries the batch never reached before its time limit come back with `skipped:true` and `code:batch_deadline`; resend exactly those to resume.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        messages: {
+          type: "array",
+          minItems: 1,
+          maxItems: 200,
+          items: {
+            type: "object",
+            properties: {
+              chat_id: { type: "string", minLength: 1, maxLength: 500 },
+              message_id: { type: "string", minLength: 1, maxLength: 500 },
+            },
+            required: ["chat_id", "message_id"],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ["messages"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "email_list",
     path: "/email/list",
-    description: "List the newest message from each recent email thread. args: limit",
+    description: "List the newest message from each recent email thread. args: limit, cursor",
     inputSchema: {
       type: "object",
-      properties: { limit: { type: "integer", minimum: 1, maximum: 100 } },
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+        cursor: {
+          type: "string",
+          minLength: 1,
+          maxLength: 4096,
+          description: "Fetch the next page. Use the cursor returned by a previous email_list.",
+        },
+      },
+      additionalProperties: false,
     },
   },
   {
@@ -579,12 +1133,13 @@ const TOOLS = [
         limit: { type: "integer", minimum: 1, maximum: 100 },
       },
       required: ["thread_id"],
+      additionalProperties: false,
     },
   },
   {
     name: "email_send",
     path: "/email/send",
-    description: "Send one approved email after reading that recipient's thread. args: to, subject, body",
+    description: "Send one approved email after reading that recipient's thread. Pass thread_id from email_read to reply inside that thread rather than starting a new one. args: to, subject, body, thread_id",
     inputSchema: {
       type: "object",
       properties: {
@@ -596,19 +1151,217 @@ const TOOLS = [
         },
         subject: { type: "string", minLength: 1, maxLength: 998 },
         body: { type: "string", minLength: 1, maxLength: 5000 },
+        thread_id: {
+          type: "string",
+          minLength: 1,
+          maxLength: 500,
+          description: "Reply inside this thread. Use the thread_id returned by email_read.",
+        },
+        confirm_resend: {
+          type: "boolean",
+          description: "Only after a send_outcome_unknown refusal, and only once you have read the thread again and confirmed the email is genuinely absent.",
+        },
       },
       required: ["to", "subject", "body"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_my_posts",
+    path: "/li/posts",
+    description: "List the user's own LinkedIn posts with engagement counts (reactions, comments, impressions). args: limit",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 50 },
+        member_id: { type: "string", minLength: 1, maxLength: 500, description: "Whose posts to list. Defaults to your own." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_post_reactions",
+    path: "/li/post_reactions",
+    description: "Who reacted to a post — name + headline. These are warm inbound signals. args: post_id, limit",
+    inputSchema: {
+      type: "object",
+      properties: {
+        post_id: { type: "string", minLength: 1, maxLength: 500 },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+      },
+      required: ["post_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_post_comments",
+    path: "/li/post_comments",
+    description: "Comments on a post, with author. args: post_id, limit",
+    inputSchema: {
+      type: "object",
+      properties: {
+        post_id: { type: "string", minLength: 1, maxLength: 500 },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+      },
+      required: ["post_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_draft_post",
+    path: "/li/create_post",
+    description: "Draft, publish, or schedule a LinkedIn post. Scheduling requires an offset-qualified scheduled_at plus publish:true after exact human approval. Optional mentions, base64 image attachments, and an account-owner-authored first_comment are preserved for the scheduled publish.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", minLength: 1, maxLength: 3000 },
+        publish: { type: "boolean" },
+        scheduled_at: { type: "string", format: "date-time" },
+        first_comment: { type: "string", minLength: 1, maxLength: 1250 },
+        mentions: {
+          type: "array", maxItems: 20,
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string", minLength: 1, maxLength: 120 },
+              profile_id: { type: "string", minLength: 1, maxLength: 250 },
+            },
+            required: ["name", "profile_id"],
+          },
+        },
+        attachments: {
+          type: "array", maxItems: 4,
+          items: {
+            type: "object",
+            properties: {
+              filename: { type: "string", minLength: 1, maxLength: 180 },
+              content_type: { type: "string", enum: ["image/png", "image/jpeg", "image/webp", "image/gif"] },
+              content_base64: { type: "string", minLength: 1 },
+            },
+            required: ["filename", "content_type", "content_base64"],
+          },
+        },
+      },
+      required: ["text"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_set_scheduled_post_first_comment",
+    path: "/li/set_scheduled_post_first_comment",
+    description: "Attach one exact approved first comment to an existing scheduled LinkedIn post. SignalDash publishes it through the same connected account immediately after the post. Requires id, first_comment, and confirm:true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        first_comment: { type: "string", minLength: 1, maxLength: 1250 },
+        confirm: { type: "boolean", const: true },
+      },
+      required: ["id", "first_comment", "confirm"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "li_scheduled_posts",
+    path: "/li/scheduled_posts",
+    description: "List this authenticated user's scheduled LinkedIn posts and their current states.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "li_cancel_scheduled_post",
+    path: "/li/cancel_scheduled_post",
+    description: "Cancel one exact scheduled LinkedIn post before execution. Requires id and confirm:true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        confirm: { type: "boolean", const: true },
+      },
+      required: ["id", "confirm"],
+      additionalProperties: false,
+    },
+  },
+  // sd_, not wa_ or li_, because these three carry `channel` and act on either
+  // one. The prefixes here are a claim about scope: wa_ and li_ tools reach
+  // exactly one network and their arguments say so, and every tool that spans
+  // both or belongs to SignalDash itself is sd_ already, from sd_contact_state
+  // through the sd_campaign_ and sd_withdrawal_batch_ families.
+  {
+    name: "sd_schedule_message",
+    path: "/sd/schedule_message",
+    description: "Schedule ONE exact message into ONE chat you have already read, on WhatsApp or LinkedIn. Read that exact chat first, at limit 10 or more on LinkedIn: SignalDash records what the thread looked like and refuses to send if the conversation moved before the scheduled time. Requires confirm:true after the human approves the exact channel, chat, text, and time. Text only, no attachments. This is not a follow-up sequence and there is no recurrence: one message, one time.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channel: { type: "string", enum: ["whatsapp", "linkedin"] },
+        chat_id: { type: "string", minLength: 1, maxLength: 500 },
+        text: { type: "string", minLength: 1, maxLength: 5000 },
+        scheduled_at: { type: "string", format: "date-time" },
+        confirm: { type: "boolean", const: true },
+      },
+      required: ["channel", "chat_id", "text", "scheduled_at", "confirm"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_scheduled_messages",
+    path: "/sd/scheduled_messages",
+    description: "List this authenticated user's scheduled messages and their durable states, optionally filtered by state or channel. Always reports needs_review_count outside that filter: a message in needs_review stopped at send time and is waiting on a human.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        state: {
+          type: "string",
+          enum: [
+            "scheduled",
+            "executing",
+            "sent",
+            "cancelled",
+            "failed",
+            "needs_review",
+          ],
+        },
+        channel: { type: "string", enum: ["whatsapp", "linkedin"] },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "sd_cancel_scheduled_message",
+    path: "/sd/cancel_scheduled_message",
+    description: "Cancel one exact scheduled message while it is still scheduled. Requires id and confirm:true. It cannot stop a message already being sent, and it cannot unsend one that has been sent.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        confirm: { type: "boolean", const: true },
+      },
+      required: ["id", "confirm"],
+      additionalProperties: false,
     },
   },
-  { name: "li_my_posts", path: "/li/posts", description: "List the user's own LinkedIn posts with engagement counts (reactions, comments, impressions). args: limit" },
-  { name: "li_post_reactions", path: "/li/post_reactions", description: "Who reacted to a post — name + headline. These are warm inbound signals. args: post_id, limit" },
-  { name: "li_post_comments", path: "/li/post_comments", description: "Comments on a post, with author. args: post_id, limit" },
-  { name: "li_draft_post", path: "/li/create_post", description: "Draft a LinkedIn post. Returns the draft WITHOUT publishing. Publishing requires the human to approve and re-send with publish:true. args: text" },
 ];
+// No catch-all fallback. It advertised one union of keys for every tool that
+// had no schema of its own -- which is how `li_list_chats` came to offer `text`
+// and `member_id` that the route never reads, and how a caller could not tell a
+// filtered search from an unfiltered list.
+//
+// A tool with no schema is dropped from the listing rather than shipped with a
+// promise the backend does not keep. Dropped, not thrown: tools/list maps every
+// tool through here, so throwing would take the whole LinkedIn AND WhatsApp
+// surface down over one bad entry. The test suite is what fails on a missing
+// schema; the live surface degrades by exactly one tool.
 function mcpTool(name) {
   const tool = TOOLS.find(t => t.name === name);
-  return { name, description: tool.description,
-    inputSchema: tool.inputSchema || { type: "object", properties: { chat_id: { type: "string" }, text: { type: "string" }, limit: { type: "number" }, post_id: { type: "string" }, member_id: { type: "string" }, publish: { type: "boolean" } } } };
+  if (!tool || !tool.inputSchema) {
+    process.stderr.write(`[signaldash] tool ${name} has no inputSchema; omitted\n`);
+    return null;
+  }
+  return {
+    name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  };
 }
 export async function runMcp(dependencies = {}) {
   const input = dependencies.input || process.stdin;
@@ -620,7 +1373,7 @@ export async function runMcp(dependencies = {}) {
     let msg; try { msg = JSON.parse(line); } catch { continue; }
     const { id, method, params } = msg;
     if (method === "initialize") reply(id, { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "signaldash", version: PACKAGE_VERSION } });
-    else if (method === "tools/list") reply(id, { tools: TOOLS.map(t => mcpTool(t.name)) });
+    else if (method === "tools/list") reply(id, { tools: TOOLS.map(t => mcpTool(t.name)).filter(Boolean) });
     else if (method === "tools/call") {
       const t = TOOLS.find(x => x.name === params.name);
       if (!t) { reply(id, null, { code: -32601, message: "unknown tool" }); continue; }
@@ -640,7 +1393,14 @@ export async function cmdSkill(dependencies = {}) {
   if (!ex(src)) { log("skill file not found in package"); process.exitCode = 1; return; }
   const dest = join(homedir(), ".claude", "skills", "signaldash");
   mk(dest, { recursive: true });
-  wf(join(dest, "SKILL.md"), rf(src, "utf8"));
+  // The template pins the bootstrap command to a version placeholder rather
+  // than a typed-in string: package.json is the only source of truth, so an
+  // installed skill can never advertise a stale published release. Rendered
+  // by the shared helper (lib/skill-template.cjs) so this substitution has a
+  // single source of truth shared with the public skill page and the
+  // server's own /skill and /skill.md routes.
+  const template = rf(src, "utf8");
+  wf(join(dest, "SKILL.md"), renderSkillTemplate(template, PACKAGE_VERSION));
   log(`Installed the SignalDash skill to ${dest}/SKILL.md`);
   log("Your agent now knows how to use LinkedIn + WhatsApp safely through SignalDash.");
 }
@@ -664,7 +1424,7 @@ export async function cmdSetup(code, dependencies = {}) {
   log("  " + chalk.green("+") + " agent skill installed");
 
   try {
-    execSync("claude mcp add signaldash -- npx -y @floomhq/signaldash mcp", { stdio: "ignore" });
+    execSync("claude mcp add signaldash -s user -- npx -y @floomhq/signaldash mcp", { stdio: "ignore" });
     log("  " + chalk.green("+") + " MCP registered with Claude Code");
   } catch {
     log("  " + chalk.yellow("!") + " Claude Code not found. For Cursor, add to .cursor/mcp.json:");
@@ -763,6 +1523,7 @@ function printHelp(log = console.log) {
   log(`SignalDash \u2014 secure LinkedIn, WhatsApp and email access for your AI agent.
 
   signaldash <invite-code>              set up everything in one go
+  signaldash login-token <token>        store a session token you were given
   signaldash status                     show what is connected
   signaldash connect linkedin|whatsapp|email
   signaldash connections [file.csv]     export your LinkedIn connections
@@ -778,8 +1539,9 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   const [cmd, a, b, c] = argv;
   const log = dependencies.log || console.log;
   if (cmd === "setup") await cmdSetup(a, dependencies);
-  else if (cmd && /^[0-9a-f]{8,}$/i.test(cmd) && !["login","logout","connect","mcp","skill"].includes(cmd)) await cmdSetup(cmd, dependencies);
+  else if (cmd && INVITE_CODE_REGEX.test(cmd) && !["login","logout","connect","mcp","skill"].includes(cmd)) await cmdSetup(cmd, dependencies);
   else if (cmd === "login") await cmdLogin(a, b === "--backend" ? c : undefined, dependencies);
+  else if (cmd === "login-token") await cmdLoginToken(a, b === "--backend" ? c : undefined, dependencies);
   else if (cmd === "logout") await cmdLogout(dependencies);
   else if (cmd === "connect" && b === "claim") await cmdClaim(a, c, dependencies);
   else if (cmd === "connect") await cmdConnect(a, dependencies);
@@ -788,8 +1550,7 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   else if (cmd === "connections" || (cmd === "export" && a === "connections")) await cmdConnections(cmd === "export" ? b : a, dependencies);
   else if (cmd === "--version" || cmd === "-v") log(PACKAGE_VERSION);
   else if (cmd === "skill") await cmdSkill(dependencies);
-  else if (cmd === "logout") await cmdLogout(dependencies);
-  else if (cmd && !["help","--help","-h"].includes(cmd) && !/^[0-9a-f]{8,}$/i.test(cmd)) { (dependencies.error || console.error)(`unknown command: ${cmd}`); printHelp(log); process.exitCode = 1; }
+  else if (cmd && !["help","--help","-h"].includes(cmd) && !INVITE_CODE_REGEX.test(cmd)) { (dependencies.error || console.error)(`unknown command: ${cmd}`); printHelp(log); process.exitCode = 1; }
   else printHelp(log);
 }