relay-companion 0.1.99 → 0.1.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.99",
+  "version": "0.1.100",
   "description": "Relay companion for ordinary messages, with dormant coordination features available only by explicit opt-in.",
   "type": "module",
   "bin": {

package/src/mcp.js

@@ -14,7 +14,7 @@ export const TOOLS = [
   {
     name: "relay_send",
     description:
-      "Send an ordinary Relay message or handoff. Use this for the normal product flow when the human says things like 'send Sven a relay asking how he is doing' or 'relay this context to Jordan'. THREADING: Relay groups messages into conversation threads built from reply chains, so before sending, check the recent exchange with this recipient — call relay_inbox_list for what they sent this human (each item carries threadId and inReplyToRelayId), and use the sent context you already have from earlier sends. If the new message continues an ongoing exchange — topically, or within a recent back-and-forth window — pass inReplyToRelayId set to the LATEST relay id of that exchange (whichever side sent it) so the conversation stays one thread. If it starts a new topic, omit inReplyToRelayId and send it standalone. A thread has a NAME the human scans in their Relay list: whenever you reply into a thread that is not already well named, pass threadTitle to name the conversation (see that field). Granular digital employees appear as managed, workspace-labelled contacts; use relay_contacts_search and pass the exact matching contactId so a user with several workspaces reaches the intended employee. That message is authored by this human and wakes their employee; it is NOT a Relay task or deterministic workflow. Never use task-only tools to contact a Granular employee. For other recipients, an on-Relay message appears in their companion and Relays list; an off-Relay recipient receives an email open link.",
+      "Send an ordinary Relay message or handoff. Use this for the normal product flow when the human says things like 'send Sven a relay asking how he is doing' or 'relay this context to Jordan'. THREADING — check this before EVERY send: Relay groups messages into conversation threads built from reply chains, and a thread only comes into existence when the sender links the messages, so an unlinked follow-up is lost as a standalone relay forever. Look at BOTH sides of the recent exchange with this recipient: relay_sent_list for what this human already sent them, and relay_inbox_list for what they sent back. You MUST call relay_sent_list rather than rely on memory — your own earlier sends are not in relay_inbox_list, and a send from a previous session is not in your context. If the new message continues an existing exchange, pass inReplyToRelayId set to the LATEST relay id of that exchange (whichever side sent it) so the conversation stays one thread. A one-way series of updates is still one exchange: rounds 2, 3 and 4 of a piece of work, a correction, or a status update on something you already relayed this person all belong on the first message's thread — not in four standalone relays the human has to reassemble. Omit inReplyToRelayId only when this genuinely opens a subject you have not relayed this person about. A thread also has a NAME the human scans in their Relay list: whenever you continue a thread that is not already well named, pass threadTitle to name the conversation (see that field). Granular digital employees appear as managed, workspace-labelled contacts; use relay_contacts_search and pass the exact matching contactId so a user with several workspaces reaches the intended employee. That message is authored by this human and wakes their employee; it is NOT a Relay task or deterministic workflow. Never use task-only tools to contact a Granular employee. For other recipients, an on-Relay message appears in their companion and Relays list; an off-Relay recipient receives an email open link.",
     inputSchema: {
       type: "object",
       properties: {
@@ -77,12 +77,12 @@ export const TOOLS = [
         inReplyToRelayId: {
           type: "string",
           description:
-            "The id of the relay this message replies to. Threads are built from reply chains: when continuing an ongoing exchange, reply to the NEWEST relay in that exchange (from relay_inbox_list or an earlier send), never an older one, so the whole conversation shares one thread. Omit it to start a new standalone thread. When answering a question relay, pass that relay's id here — this is what resumes the asking agent's run.",
+            "The id of the relay this message replies to or follows up on — the one field that puts this message into an existing conversation instead of starting a new one. Threads are built from reply chains, so pass the NEWEST relay id in that exchange, never an older one, and the whole conversation shares one thread. Find it in relay_sent_list (this human's own earlier sends — the usual source when following up on your own message), relay_inbox_list (what the other person sent), or the relayId returned by an earlier relay_send in this same session. This does not have to be a literal answer to a question: a follow-up, a next round, a revision, or a status update on something you already relayed this person is a continuation and belongs on the same thread. Omit it only to open a genuinely new subject. When answering a question relay, pass that relay's id here — this is what resumes the asking agent's run.",
         },
         threadTitle: {
           type: "string",
           description:
-            "Name the CONVERSATION (not this message). A thread comes into existence the moment a relay replies to another, and its name is what both people scan in their Relay list ever after — so whenever you send a reply (inReplyToRelayId set) into a thread that is not already well named, title it here. Same discipline as `title`, one level up: in as few words as it honestly takes (~5-12 words, hard stop 140 characters), say what this exchange IS and what it is for, so someone reading the list weeks later knows whether to open it. Name the ongoing subject, not the latest turn: 'Postmark migration for sendrelays.com — DNS + verification' beats 'Re: DNS records' or 'Postmark'. Never a bare noun ('Update', 'Question'), never a timestamp, never the other person's name alone. Setting it again renames the thread — use that when a conversation genuinely changes subject, and leave it alone when the existing name still fits.",
+            "Name the CONVERSATION (not this message). A thread comes into existence the moment a relay replies to another, and its name is what both people scan in their Relay list ever after — so whenever you continue a thread (inReplyToRelayId set) that is not already well named, title it here. threadTitle only names a conversation that actually exists: setting it WITHOUT inReplyToRelayId merely labels a brand-new one-message thread and groups this relay with nothing, so if you meant to continue an exchange, find its newest relay with relay_sent_list and set inReplyToRelayId as well. Same discipline as `title`, one level up: in as few words as it honestly takes (~5-12 words, hard stop 140 characters), say what this exchange IS and what it is for, so someone reading the list weeks later knows whether to open it. Name the ongoing subject, not the latest turn: 'Postmark migration for sendrelays.com — DNS + verification' beats 'Re: DNS records' or 'Postmark'. Never a bare noun ('Update', 'Question'), never a timestamp, never the other person's name alone. Setting it again renames the thread — use that when a conversation genuinely changes subject, and leave it alone when the existing name still fits.",
         },
         type: {
           type: "string",
@@ -180,13 +180,32 @@ export const TOOLS = [
   {
     name: "relay_inbox_list",
     description:
-      "List ordinary Relay messages addressed to this human. Each item carries threadId (the conversation thread it belongs to — the root relay's id) and, on replies, inReplyToRelayId; use them to reconstruct the recent exchange with a sender before continuing it via relay_send's inReplyToRelayId. This does not list task coordination relays; use relay_task_status for task state.",
+      "List ordinary Relay messages addressed to this human — the INBOUND half of their correspondence only. Each item carries threadId (the conversation thread it belongs to — the root relay's id) and, on replies, inReplyToRelayId; use them to reconstruct the recent exchange with a sender before continuing it via relay_send's inReplyToRelayId. Relays this human SENT are not here: to follow up on one of their own earlier messages, call relay_sent_list. This does not list task coordination relays; use relay_task_status for task state.",
     inputSchema: { type: "object", properties: {} },
   },
+  {
+    name: "relay_sent_list",
+    description:
+      "List the ordinary relays this human has SENT, newest first — the outbound counterpart to relay_inbox_list. Call this before sending anyone a follow-up, a next round, or an update on something already relayed to them. Each item carries the relayId, threadId and threadTitle that relay_send's inReplyToRelayId needs to keep an ongoing exchange in ONE conversation, and this is the ONLY way to obtain them: a human's own sends never appear in relay_inbox_list, and a send from an earlier session is not in your context. Pass recipient to narrow to one correspondent; the first item back is then the newest relay in that exchange, which is exactly what inReplyToRelayId wants. Message bodies are omitted to keep the list small — read a full exchange with relay_thread_fetch on any item's threadId.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        recipient: {
+          type: "string",
+          description:
+            "Optional case-insensitive substring of the recipient's name, email, or group name, e.g. 'sven' or 'sven@example.com'. Strongly preferred when following up with a specific person.",
+        },
+        limit: {
+          type: "number",
+          description: "How many sends to return, newest first. Defaults to 20; capped at 100.",
+        },
+      },
+    },
+  },
   {
     name: "relay_thread_fetch",
     description:
-      "Fetch ONE full Relay conversation thread, oldest first: its threadTitle (the conversation's name — check it before replying; if it is missing or no longer describes the exchange, pass a better one as relay_send's threadTitle) and every relay in the exchange (both directions) with sender, recipients, timestamps, title, body, and read state. Use this whenever a relay you are opening or replying to is part of a thread (its threadId differs from its own id, or an Open-in-chat instruction names a threadId) so the WHOLE exchange is in context before you act — never reconstruct a conversation by fetching relays one at a time. Pass the threadId (the root relay's id, carried on every relay_inbox_list item).",
+      "Fetch ONE full Relay conversation thread, oldest first: its threadTitle (the conversation's name — check it before replying; if it is missing or no longer describes the exchange, pass a better one as relay_send's threadTitle) and every relay in the exchange (both directions) with sender, recipients, timestamps, title, body, and read state. Use this whenever a relay you are opening or replying to is part of a thread (its threadId differs from its own id, or an Open-in-chat instruction names a threadId) so the WHOLE exchange is in context before you act — never reconstruct a conversation by fetching relays one at a time. Pass the threadId (the root relay's id), which is carried on every relay_inbox_list and relay_sent_list item and returned by relay_send.",
     inputSchema: {
       type: "object",
       properties: {
@@ -559,10 +578,55 @@ export const MESSAGE_ONLY_TOOL_NAMES = new Set([
   "relay_group_update",
   "relay_group_delete",
   "relay_inbox_list",
+  // The sender-side history an agent needs to thread a follow-up. Without it,
+  // ordinary messaging can only ever start new conversations.
+  "relay_sent_list",
   "relay_thread_fetch",
   "relay_acknowledge",
 ]);
 
+const SENT_LIST_DEFAULT_LIMIT = 20;
+const SENT_LIST_MAX_LIMIT = 100;
+
+/**
+ * The threading-relevant shape of one sent relay. Bodies, previews and
+ * attachment descriptors are dropped: a full sent list runs to hundreds of
+ * thousands of characters and can blow an agent's context on a lookup whose
+ * whole purpose is to find one id.
+ */
+function toSentSummary(item) {
+  return {
+    relayId: item?.relayId,
+    threadId: item?.threadId ?? item?.relayId,
+    ...(item?.threadTitle ? { threadTitle: item.threadTitle } : {}),
+    ...(item?.inReplyToRelayId ? { inReplyToRelayId: item.inReplyToRelayId } : {}),
+    title: item?.title,
+    recipient: {
+      name: item?.recipient?.name ?? "",
+      ...(item?.recipient?.email ? { email: item.recipient.email } : {}),
+    },
+    ...(item?.recipientGroupName ? { recipientGroupName: item.recipientGroupName } : {}),
+    createdAt: item?.createdAt,
+    ...(item?.readAt ? { readAt: item.readAt } : {}),
+    state: item?.state,
+    hasAttachments: Boolean(item?.hasAttachments),
+  };
+}
+
+function matchesRecipient(item, needle) {
+  const haystack = [item?.recipient?.name, item?.recipient?.email, item?.recipientGroupName]
+    .filter((value) => typeof value === "string")
+    .join(" ")
+    .toLowerCase();
+  return haystack.includes(needle);
+}
+
+function sentListLimit(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return SENT_LIST_DEFAULT_LIMIT;
+  return Math.min(Math.floor(parsed), SENT_LIST_MAX_LIMIT);
+}
+
 export function toolsForMode(mode = DEFAULT_COMPANION_MODE) {
   const normalized = normalizeCompanionMode(mode);
   return normalized === COMPANION_MODE_MESSAGES_ONLY
@@ -575,17 +639,30 @@ function text(obj) {
 }
 
 function relaySendResultForAgent(result) {
-  if (!result?.contact?.autoCreated) return result;
+  // Servers that predate threading hints simply omit the field, so an older API
+  // keeps working and only loses the nudge.
+  const hint = result?.threadingHint;
+  const contactNeedsWork = Boolean(result?.contact?.autoCreated);
+  if (!hint && !contactNeedsWork) return result;
+
+  const instructions = [];
+  if (hint?.message) instructions.push(hint.message);
+  if (contactNeedsWork) {
+    instructions.push(
+      result.agentInstruction ||
+        [
+          `Relay auto-added ${result.contact.email} to this human's contact book because there was no saved contact for this recipient.`,
+          "You are responsible for correcting the contact's firstName and surname with relay_contact_update if you know them from reliable context.",
+          "If you are not sure of the person's first name and surname, ask the human for clarification before editing the contact.",
+        ].join(" "),
+    );
+  }
   return {
     ...result,
-    agentInstruction:
-      result.agentInstruction ||
-      [
-        `Relay auto-added ${result.contact.email} to this human's contact book because there was no saved contact for this recipient.`,
-        "You are responsible for correcting the contact's firstName and surname with relay_contact_update if you know them from reliable context.",
-        "If you are not sure of the person's first name and surname, ask the human for clarification before editing the contact.",
-      ].join(" "),
-    nextRecommendedTool: "relay_contact_update",
+    agentInstruction: instructions.join(" "),
+    // Threading is the more urgent correction: the window to fix it closes as
+    // soon as this send settles, while a contact name can be repaired any time.
+    nextRecommendedTool: hint ? "relay_send" : "relay_contact_update",
   };
 }
 
@@ -683,6 +760,28 @@ export async function handleCall(client, name, args, { mode = DEFAULT_COMPANION_
       );
     case "relay_inbox_list":
       return text(await client.inbox());
+    case "relay_sent_list": {
+      const response = await client.sent();
+      const all = Array.isArray(response?.items) ? response.items : [];
+      const needle = typeof args.recipient === "string" ? args.recipient.trim().toLowerCase() : "";
+      const matched = needle ? all.filter((item) => matchesRecipient(item, needle)) : all;
+      const limit = sentListLimit(args.limit);
+      const items = matched.slice(0, limit).map(toSentSummary);
+      return text({
+        items,
+        matched: matched.length,
+        // A truncated list is stated outright: silently returning 20 of 60 reads
+        // as "this is everything" and would send an agent back to guessing.
+        ...(matched.length > items.length ? { truncated: true } : {}),
+        ...(needle ? { recipientFilter: args.recipient } : {}),
+        ...(items.length
+          ? {
+              agentInstruction:
+                "Items are newest first. To continue any of these conversations, pass that item's relayId as relay_send's inReplyToRelayId — for a follow-up to one person that is normally the first item. Bodies are omitted here; relay_thread_fetch on an item's threadId returns the full exchange.",
+            }
+          : {}),
+      });
+    }
     case "relay_thread_fetch":
       return text(await client.thread(args.threadId));
     case "relay_inbox_delete":