@floomhq/signaldash 0.10.0 → 0.11.0

package/README.md

@@ -1,10 +1,10 @@
 # SignalDash
 
-Secure LinkedIn and WhatsApp access for AI agents.
+Secure LinkedIn, WhatsApp, and email access for AI agents.
 
 `@floomhq/signaldash` connects your accounts through the hosted SignalDash
-service and exposes six account-scoped MCP tools. The CLI never receives or
-stores the server's Unipile access key.
+service and exposes account-scoped MCP tools. The CLI never receives or stores
+the server's Unipile access key.
 
 ## Quickstart
 
@@ -15,12 +15,14 @@ SignalDash administrator for an invite code, then run:
 npx -y @floomhq/signaldash login <invite-code>
 npx -y @floomhq/signaldash connect linkedin
 npx -y @floomhq/signaldash connect whatsapp
+npx -y @floomhq/signaldash connect email
 ```
 
 Each connect command prints a short-lived hosted-auth URL and waits for the
 connection to finish. Open the LinkedIn URL and sign in, or open the WhatsApp
-URL and scan the live QR code. The CLI prints `Connected linkedin` or
-`Connected whatsapp` when the account is ready.
+URL and scan the live QR code. The email link offers Google, Outlook, and IMAP
+when those providers are enabled on the Unipile account. The CLI prints
+`Connected <provider>` when the account is ready.
 
 The invite code is single-use. Login stores a SignalDash user token in
 `~/.signaldash/config.json`; the Unipile access key remains on the SignalDash
@@ -69,8 +71,8 @@ npx -y @floomhq/signaldash mcp
 ```
 
 The MCP server uses the user token created by `login`. It cannot access a
-LinkedIn or WhatsApp account until that channel has been connected for the
-same logged-in user.
+LinkedIn, WhatsApp, or email account until that channel has been connected for
+the same logged-in user.
 
 ## Give the agent the safety skill
 
@@ -95,6 +97,9 @@ SignalDash exposes:
 - `wa_list_chats`
 - `wa_read_messages(chat_id)`
 - `wa_send_message(chat_id, text)`
+- `email_list(limit)`
+- `email_read(thread_id, limit)`
+- `email_send(to, subject, body)`
 
 Every operation runs through the hosted SignalDash backend. Agents never
 receive the Unipile access key.
@@ -109,6 +114,8 @@ workflow around that runtime control:
   exhausted, SignalDash returns HTTP 429 with `code: "rate_limit_exceeded"` and
   `Retry-After`. Usage is persisted server-side and resets at midnight UTC.
 - Read the exact thread before every send.
+- 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.
 - Do not parallelize sends or work around a rate limit.

package/bin/sd.mjs

@@ -105,8 +105,8 @@ export async function cmdConnect(provider, dependencies = {}) {
   const now = dependencies.now || Date.now;
   const log = dependencies.log || console.log;
   const error = dependencies.error || console.error;
-  if (!["linkedin", "whatsapp"].includes(provider)) {
-    error("usage: signaldash connect linkedin|whatsapp");
+  if (!["linkedin", "whatsapp", "email"].includes(provider)) {
+    error("usage: signaldash connect linkedin|whatsapp|email");
     process.exitCode = 1;
     return;
   }
@@ -118,10 +118,18 @@ export async function cmdConnect(provider, dependencies = {}) {
     process.exitCode = 1;
     return;
   }
-  const { chalk, ora, open } = await ui();
+  const { chalk, ora, open: defaultOpen } = await ui();
+  const openUrl = dependencies.open || defaultOpen;
   log("\n  " + chalk.dim("Opening your browser. If it does not open, use this link:"));
   log("  " + chalk.cyan(r.json.url) + "\n");
-  try { await open(r.json.url); } catch {}
+  try { await openUrl(r.json.url); } catch {}
+  if (!(process.stdin.isTTY && process.stdout.isTTY) && !dependencies.forcePoll) {
+    log("");
+    log(`  ACTION REQUIRED (human): open the link above to connect ${provider}.`);
+    log(`  Then run: npx @floomhq/signaldash connect ${provider}`);
+    log("");
+    return;
+  }
   const spin = ora({ text: `Waiting for ${provider} authentication...`, indent: 2 }).start();
   dependencies._spin = spin;
 
@@ -164,14 +172,56 @@ const TOOLS = [
   { 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: "email_list",
+    path: "/email/list",
+    description: "List the newest message from each recent email thread. args: limit",
+    inputSchema: {
+      type: "object",
+      properties: { limit: { type: "integer", minimum: 1, maximum: 100 } },
+    },
+  },
+  {
+    name: "email_read",
+    path: "/email/read",
+    description: "Read an email thread before drafting or sending. args: thread_id, limit",
+    inputSchema: {
+      type: "object",
+      properties: {
+        thread_id: { type: "string", minLength: 1, maxLength: 500 },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+      },
+      required: ["thread_id"],
+    },
+  },
+  {
+    name: "email_send",
+    path: "/email/send",
+    description: "Send one approved email after reading that recipient's thread. args: to, subject, body",
+    inputSchema: {
+      type: "object",
+      properties: {
+        to: {
+          type: "array",
+          items: { type: "string", format: "email" },
+          minItems: 1,
+          maxItems: 1,
+        },
+        subject: { type: "string", minLength: 1, maxLength: 998 },
+        body: { type: "string", minLength: 1, maxLength: 5000 },
+      },
+      required: ["to", "subject", "body"],
+    },
+  },
   { 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" },
 ];
 function mcpTool(name) {
-  return { name, description: TOOLS.find(t => t.name === name).description,
-    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" } } } };
+  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" } } } };
 }
 export async function runMcp(dependencies = {}) {
   const input = dependencies.input || process.stdin;
@@ -187,7 +237,7 @@ export async function runMcp(dependencies = {}) {
     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; }
-      const r = await request(`/${t.ch}/${t.action}`, params.arguments || {});
+      const r = await request(t.path || `/${t.ch}/${t.action}`, params.arguments || {});
       reply(id, { content: [{ type: "text", text: JSON.stringify(r.json) }], isError: r.status >= 300 });
     } else if (id !== undefined) reply(id, {});
   }
@@ -235,7 +285,14 @@ export async function cmdSetup(code, dependencies = {}) {
   }
   log("");
 
-  const choice = dependencies.choice ?? (await prompts({
+  // An AGENT (Claude Code / Cursor) runs this with no TTY. Blocking on an
+  // interactive menu is why "nothing happened" for the first testers: the
+  // process stopped at a prompt nobody could answer. Non-interactive => connect
+  // both and print links the agent can relay to the human.
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  const choice = dependencies.choice ?? (!interactive
+    ? ["linkedin", "whatsapp"]
+    : (await prompts({
     type: "select",
     name: "value",
     message: "Which accounts do you want to connect?",
@@ -246,7 +303,7 @@ export async function cmdSetup(code, dependencies = {}) {
       { title: "Skip for now", value: [] },
     ],
     initial: 0,
-  })).value;
+  })).value);
 
   if (!choice || choice.length === 0) {
     log("\n  " + chalk.dim("Nothing connected. Run `signaldash connect whatsapp` or `connect linkedin` anytime."));
@@ -269,7 +326,7 @@ export async function cmdStatus(dependencies = {}) {
   const request = dependencies.request || api;
   log("");
   log("  " + chalk.bold("SignalDash") + chalk.dim("  " + (cfg.backend || DEFAULT_BACKEND)));
-  for (const provider of ["linkedin", "whatsapp"]) {
+  for (const provider of ["linkedin", "whatsapp", "email"]) {
     const r = await request(`/connect/${provider}/status`, undefined, { method: "GET" });
     const ok = r.status === 200 && r.json.connected;
     log("  " + (ok ? chalk.green("+") : chalk.dim("-")) + " " + provider.padEnd(9) +

package/package.json

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

package/skills/signaldash/SKILL.md

@@ -1,27 +1,35 @@
 ---
 name: signaldash
-description: Give this agent secure access to the user's LinkedIn and WhatsApp — list chats, read threads, and send messages — through SignalDash. Use whenever the user asks to check, read, triage, reply to, or send LinkedIn/WhatsApp messages. Also covers first-time setup.
+description: Give this agent secure access to the user's LinkedIn, WhatsApp, and email accounts through SignalDash. Use whenever the user asks to check, read, triage, draft, reply to, or send LinkedIn/WhatsApp messages or email. Also covers first-time setup.
 ---
 
-# SignalDash — LinkedIn + WhatsApp for this agent
+# SignalDash: LinkedIn, WhatsApp, and email for this agent
 
 SignalDash is the gate between you and the user's real messaging accounts. The
 user's channel credentials live on the SignalDash server, never on their machine
 and never in your context. You act through SignalDash tools only.
 
-## Setup (only if the tools are not available yet)
+## Setup (run this when the SignalDash tools are not available yet)
 
-The user needs an invite code from Federico, then:
+You are an agent, so there is no interactive terminal. Run the command, then
+RELAY THE LINKS TO THE HUMAN. They must click them; you cannot.
 
 ```bash
-npx @floomhq/signaldash login <invite-code>
-npx @floomhq/signaldash connect linkedin     # opens a link; user authenticates; auto-detects
-npx @floomhq/signaldash connect whatsapp     # same, QR scan from WhatsApp > Linked Devices
-claude mcp add signaldash -- npx -y @floomhq/signaldash mcp
+npx -y @floomhq/signaldash <invite-code>
 ```
 
-Cursor: add to `.cursor/mcp.json` →
-`{"mcpServers":{"signaldash":{"command":"npx","args":["-y","@floomhq/signaldash","mcp"]}}}`
+This logs in, installs this skill, registers the MCP server, and prints one
+`account.unipile.com` link per channel. Then:
+
+1. **Show the human the links** and tell them plainly: open this to connect
+   LinkedIn / WhatsApp. WhatsApp is a QR scan from WhatsApp > Linked Devices.
+2. After they say they have authenticated, confirm with:
+   `npx -y @floomhq/signaldash connect linkedin` (or `whatsapp`, or `email`)
+3. Check what is connected any time: `npx -y @floomhq/signaldash status`
+4. Restart the MCP connection (or the editor) so the tools load.
+
+If the human has no invite code, they need one from Federico. Without it,
+nothing else in this skill works.
 
 ## Tools
 
@@ -33,13 +41,19 @@ Cursor: add to `.cursor/mcp.json` →
 | `wa_list_chats` | list the user's WhatsApp chats |
 | `wa_read_messages` | read a WhatsApp thread (`chat_id`) |
 | `wa_send_message` | send a WhatsApp message (`chat_id`, `text`) |
+| `email_list` | list the newest message from each recent email thread (`limit`) |
+| `email_read` | read an email thread (`thread_id`, `limit`) |
+| `email_send` | send one email (`to`, `subject`, `body`) |
 
 ## Enforced by the server (you cannot bypass these)
 
 - **Read before send.** Sending to a chat you have not read recently returns
   `428 read_before_send_required`. Call `*_read_messages` on that chat first.
+  Email sends require a recent `email_read` whose thread contains the exact
+  recipient address.
 - **No double-send.** An identical message to the same chat returns
-  `409 duplicate_send`.
+  `409 duplicate_send`. The same guard fingerprints email recipient, subject,
+  and body.
 - **Daily send cap + pacing.** Exceeding it returns `429 rate_limit_exceeded`.
 
 These are server-side guards, not suggestions. Do not try to work around them.
@@ -52,8 +66,9 @@ them from you sending something wrong. They are not optional.
 1. **Never send without the user's explicit approval of the exact recipient and
    exact text.** Draft it, show it, wait. Discussion is not approval.
 2. **Read the thread before you send.** Always `*_read_messages` on that exact
-   chat first: check who it is, what they last said, and whether this was
-   already sent. Never send blind. Never double-send.
+   chat or `email_read` on the exact mail thread first: check who it is, what
+   they last said, and whether this was already sent. Never send blind. Never
+   double-send.
 3. **Never bulk.** No mass messaging, no "message everyone who…", no bulk
    profile fetching. LinkedIn restricts accounts for exactly this. Hard ceiling
    is roughly 15-20 LinkedIn sends per day; the server enforces a daily cap and
@@ -65,6 +80,16 @@ them from you sending something wrong. They are not optional.
 6. **Personalize.** Read the thread and write a specific reply. Templated
    identical messages get reported as spam.
 
+## Email-specific rules
+
+- `email_send` accepts exactly one recipient. Do not split bulk sends into
+  repeated calls.
+- Obtain explicit approval for the exact recipient, subject, and body.
+- Read the recipient's recent thread immediately before sending. If there is no
+  existing thread, do not send through SignalDash.
+- Stop on provider authentication errors, HTTP 403, or HTTP 429. Do not retry an
+  ambiguous timeout until the mailbox and sent history have been re-read.
+
 ## Good vs bad requests
 
 Good: "list my unread LinkedIn chats and draft replies for my approval" ·

package/skills/signaldash-safe-usage/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: signaldash-safe-usage
-description: Safely read and send LinkedIn or WhatsApp messages through the SignalDash MCP without triggering account restrictions or contacting the wrong person. Use whenever an agent uses li_list_chats, li_read_messages, li_send_message, wa_list_chats, wa_read_messages, or wa_send_message.
+description: Safely read and send LinkedIn, WhatsApp, or email messages through the SignalDash MCP without triggering account restrictions or contacting the wrong person. Use whenever an agent uses li_list_chats, li_read_messages, li_send_message, wa_list_chats, wa_read_messages, wa_send_message, email_list, email_read, or email_send.
 ---
 
 # Use SignalDash safely
 
-Treat LinkedIn and WhatsApp as human accounts, not bulk messaging APIs.
+Treat LinkedIn, WhatsApp, and email as human accounts, not bulk messaging APIs.
 
 ## Before every send
 
 1. Confirm the requested channel and exact chat.
-2. Use `li_list_chats` or `wa_list_chats`; never fetch profiles in bulk.
-3. Read at least the 10 most recent messages in the exact thread.
+2. Use `li_list_chats`, `wa_list_chats`, or `email_list`; never fetch profiles
+   or mailboxes in bulk.
+3. Read at least the 10 most recent messages in the exact thread with
+   `li_read_messages`, `wa_read_messages`, or `email_read`.
 4. Check the recipient, prior conversation, last inbound message, and whether
    the proposed text was already sent.
 5. Obtain explicit human approval for the exact recipient and exact text when
@@ -21,6 +23,18 @@ Treat LinkedIn and WhatsApp as human accounts, not bulk messaging APIs.
 Never infer a recipient from a partial name. Never send blind. Never retry a
 send after an ambiguous timeout without first reading the thread.
 
+## Email limits
+
+- `email_send` accepts one recipient per call. Never loop to simulate a bulk
+  send.
+- Approve and verify the exact recipient, subject, and body.
+- The server requires a recent `email_read` containing that recipient address,
+  blocks exact duplicates, and counts the send against the persisted daily cap.
+- If no prior thread exists with the recipient, do not send through SignalDash.
+- Stop on authentication errors, HTTP 403, HTTP 429, bounces, or provider
+  warnings. Re-read the mailbox and sent history before resolving any ambiguous
+  send outcome.
+
 ## LinkedIn limits
 
 - Keep normal messaging at 15 to 20 sends per day. SignalDash hard-caps at 18