@hmawla/co-assistant 1.0.7 → 1.0.8

package/heartbeats/email-reply-check.heartbeat.md

@@ -2,30 +2,29 @@ You are checking my recent emails for any that require a reply from me.
 
 ## Instructions
 
-1. Use the `gmail_search_emails` tool to fetch my last 5 emails (query: `in:inbox`, maxResults: 5).
-2. For each email, use `gmail_read_email` to read its full content.
-3. Skip any email whose message ID appears in the deduplication list below.
-4. For each **new** email, determine whether it requires a reply from me. Consider:
+1. Use `gmail__search_threads` to fetch my recent inbox threads (query: `in:inbox`, maxThreads: 18, **includeLatestBody: true**). This single call returns all threads with every message (including your sent replies) and the full body of the latest message. **Do NOT call any other Gmail tools** — this gives you everything you need.
+2. Skip any thread whose latest message ID appears in the deduplication list below. Also skip newsletters, automated notifications, marketing, no-reply senders, and receipts.
+3. For each remaining thread, check the `lastMessageIsSent` field. **If `lastMessageIsSent` is true, I already replied — SKIP this thread.**
+4. Only for threads where `lastMessageIsSent` is false, determine whether it requires a reply from me. Consider:
    - Direct questions asked to me
    - Action items or requests directed at me
    - Invitations or RSVPs awaiting my response
    - Important threads where I'm expected to respond
-   - Do NOT flag: newsletters, automated notifications, marketing, no-reply senders, receipts
-5. For each email that needs a reply, suggest a concise, professional reply draft.
+5. For each thread that needs a reply, suggest a concise, professional reply draft based on the latest incoming message body.
 
 ## Output Format
 
-For each email that needs a reply, format your output like this:
+For each thread that needs a reply, output exactly ONE entry (not one per message):
 
-**📧 From:** [sender]
-**Subject:** [subject]
-**Why reply:** [brief reason]
+**📧 From:** [sender of the latest message]
+**Subject:** [thread subject]
+**Why reply:** [brief reason based on the latest message in the thread]
 **Suggested reply:**
 > [your suggested reply text]
 
 ---
 
-If no emails require a reply, do not say anything unless invoked with /heartbeat
+If no threads require a reply, do not say anything unless invoked with /heartbeat
 
 ## Deduplication
 
@@ -33,7 +32,7 @@ If no emails require a reply, do not say anything unless invoked with /heartbeat
 
 ## IMPORTANT — Deduplication Marker
 
-At the very end of your response, you MUST output exactly one line in this format with ALL email message IDs you checked (whether they needed a reply or not). This prevents re-checking the same emails next time:
+At the very end of your response, you MUST output exactly one line in this format with the message ID of the **most recent message per thread** you checked (whether it needed a reply or not). Only one ID per thread. This prevents re-checking the same threads next time:
 
-<!-- PROCESSED: msg_id_1, msg_id_2, msg_id_3, msg_id_4, msg_id_5 -->
-Also, make sure to not output the same message id multiple times, so if it exist don't push it.
+<!-- PROCESSED: latest_msg_id_thread1, latest_msg_id_thread2, latest_msg_id_thread3 -->
+Do not output the same message ID multiple times.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmawla/co-assistant",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "AI-powered Telegram personal assistant using GitHub Copilot SDK",
   "type": "module",
   "main": "dist/index.js",

package/plugins/gmail/index.compiled.mjs

@@ -13877,18 +13877,22 @@ function extractBody(payload) {
 function createGmailTools(auth, logger) {
   const searchEmails = {
     name: "search_emails",
-    description: "Search for emails in Gmail using a query string (same syntax as the Gmail search bar)",
+    description: "Search for emails in Gmail. Returns metadata by default; set includeBody=true to also return full message bodies (avoids needing separate read_email calls).",
     parameters: external_exports.object({
       /** Gmail search query (e.g. "from:alice subject:meeting"). */
       query: external_exports.string().describe("Gmail search query"),
       /** Maximum number of results to return (default 10, max 50). */
-      maxResults: external_exports.number().int().min(1).max(50).optional().default(10).describe("Maximum number of results to return")
+      maxResults: external_exports.number().int().min(1).max(50).optional().default(10).describe("Maximum number of results to return"),
+      /** When true, fetches full message bodies inline. Slower per message but
+       *  eliminates the need for separate read_email calls. */
+      includeBody: external_exports.boolean().optional().default(false).describe("Include full message body in results")
     }),
     handler: async (args) => {
       try {
         const query = args.query;
         const maxResults = args.maxResults ?? 10;
-        logger.debug({ query, maxResults }, "search_emails called");
+        const includeBody = args.includeBody ?? false;
+        logger.debug({ query, maxResults, includeBody }, "search_emails called");
         const params = new URLSearchParams({
           q: query,
           maxResults: String(maxResults)
@@ -13905,24 +13909,28 @@ function createGmailTools(auth, logger) {
         if (!listData.messages?.length) {
           return "No emails found matching that query.";
         }
+        const format = includeBody ? "full" : "metadata";
         const headers = await authHeaders(auth);
         const results = await Promise.all(
           listData.messages.map(async (msg) => {
-            const msgRes = await fetch(
-              `${GMAIL_API}/messages/${msg.id}?format=metadata&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=Date`,
-              { headers }
-            );
+            const url2 = includeBody ? `${GMAIL_API}/messages/${msg.id}?format=${format}` : `${GMAIL_API}/messages/${msg.id}?format=${format}&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=Date`;
+            const msgRes = await fetch(url2, { headers });
             if (!msgRes.ok) {
-              return { id: msg.id, error: `Failed to fetch (${msgRes.status})` };
+              return { id: msg.id, threadId: msg.threadId, error: `Failed to fetch (${msgRes.status})` };
             }
             const msgData = await msgRes.json();
-            return {
+            const result = {
               id: msgData.id,
+              threadId: msgData.threadId,
               subject: getHeader(msgData.payload.headers, "Subject"),
               from: getHeader(msgData.payload.headers, "From"),
               date: getHeader(msgData.payload.headers, "Date"),
               snippet: msgData.snippet
             };
+            if (includeBody) {
+              result.body = extractBody(msgData.payload);
+            }
+            return result;
           })
         );
         return {
@@ -14030,7 +14038,135 @@ function createGmailTools(auth, logger) {
       }
     }
   };
-  return [searchEmails, readEmail, sendEmail];
+  const getThread = {
+    name: "get_thread",
+    description: "Get all messages in a Gmail thread (including your sent replies). Use this to check if you already replied to a conversation before suggesting a new reply.",
+    parameters: external_exports.object({
+      /** The Gmail thread ID (returned by search_emails or read_email). */
+      threadId: external_exports.string().describe("Gmail thread ID")
+    }),
+    handler: async (args) => {
+      try {
+        const threadId = args.threadId;
+        logger.debug({ threadId }, "get_thread called");
+        const res = await fetch(
+          `${GMAIL_API}/threads/${threadId}?format=metadata&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=To&metadataHeaders=Date`,
+          { headers: await authHeaders(auth) }
+        );
+        if (!res.ok) {
+          const errText = await res.text();
+          logger.error({ status: res.status, errText }, "Gmail get_thread failed");
+          return `Error getting thread (${res.status}): ${errText}`;
+        }
+        const data = await res.json();
+        const messages = data.messages.map((msg) => ({
+          id: msg.id,
+          from: getHeader(msg.payload.headers, "From"),
+          to: getHeader(msg.payload.headers, "To"),
+          date: getHeader(msg.payload.headers, "Date"),
+          snippet: msg.snippet,
+          isSent: msg.labelIds?.includes("SENT") ?? false
+        }));
+        return {
+          threadId: data.id,
+          messageCount: messages.length,
+          messages
+        };
+      } catch (error48) {
+        const message = error48 instanceof Error ? error48.message : String(error48);
+        logger.error({ error: message }, "get_thread error");
+        return `Error getting thread: ${message}`;
+      }
+    }
+  };
+  const searchThreads = {
+    name: "search_threads",
+    description: "Search Gmail and return results grouped by thread. Each thread includes ALL messages (including your sent replies) with isSent flags, so you can tell at a glance whether you already replied. Ideal for inbox review \u2014 returns everything in a single call.",
+    parameters: external_exports.object({
+      /** Gmail search query (e.g. "in:inbox", "from:alice"). */
+      query: external_exports.string().describe("Gmail search query"),
+      /** Maximum threads to return (default 5, max 20). */
+      maxThreads: external_exports.number().int().min(1).max(20).optional().default(5).describe("Maximum number of threads to return"),
+      /** When true, includes the full decoded body of the latest message in
+       *  each thread. When false, only snippets are returned. */
+      includeLatestBody: external_exports.boolean().optional().default(false).describe("Include full body of the latest message per thread")
+    }),
+    handler: async (args) => {
+      try {
+        const query = args.query;
+        const maxThreads = args.maxThreads ?? 5;
+        const includeLatestBody = args.includeLatestBody ?? false;
+        logger.debug({ query, maxThreads, includeLatestBody }, "search_threads called");
+        const params = new URLSearchParams({
+          q: query,
+          maxResults: String(maxThreads)
+        });
+        const listRes = await fetch(`${GMAIL_API}/threads?${params}`, {
+          headers: await authHeaders(auth)
+        });
+        if (!listRes.ok) {
+          const errText = await listRes.text();
+          logger.error({ status: listRes.status, errText }, "Gmail threads search failed");
+          return `Error searching threads (${listRes.status}): ${errText}`;
+        }
+        const listData = await listRes.json();
+        if (!listData.threads?.length) {
+          return { threadCount: 0, threads: [] };
+        }
+        const format = includeLatestBody ? "full" : "metadata";
+        const headers = await authHeaders(auth);
+        const threads = await Promise.all(
+          listData.threads.map(async (t) => {
+            const url2 = `${GMAIL_API}/threads/${t.id}?format=${format}&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=To&metadataHeaders=Date`;
+            const res = await fetch(url2, { headers });
+            if (!res.ok) {
+              return { threadId: t.id, error: `Failed to fetch (${res.status})` };
+            }
+            const data = await res.json();
+            const messages = data.messages.map((msg) => {
+              const result = {
+                id: msg.id,
+                from: getHeader(msg.payload.headers, "From"),
+                to: getHeader(msg.payload.headers, "To"),
+                date: getHeader(msg.payload.headers, "Date"),
+                snippet: msg.snippet,
+                isSent: msg.labelIds?.includes("SENT") ?? false
+              };
+              return result;
+            });
+            const latest = data.messages[data.messages.length - 1];
+            const lastIsSent = latest?.labelIds?.includes("SENT") ?? false;
+            const subject = getHeader(
+              data.messages[0].payload.headers,
+              "Subject"
+            );
+            const thread = {
+              threadId: data.id,
+              subject,
+              messageCount: messages.length,
+              lastMessageIsSent: lastIsSent,
+              messages
+            };
+            if (includeLatestBody && latest) {
+              thread.latestBody = extractBody(
+                latest.payload
+              );
+            }
+            return thread;
+          })
+        );
+        return {
+          threadCount: threads.length,
+          threads
+        };
+      } catch (error48) {
+        const message = error48 instanceof Error ? error48.message : String(error48);
+        logger.error({ error: message }, "search_threads error");
+        return `Error searching threads: ${message}`;
+      }
+    }
+  };
+  return [searchEmails, readEmail, sendEmail, getThread, searchThreads];
 }
 
 // plugins/gmail/index.ts

package/plugins/gmail/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "gmail",
   "name": "Gmail Plugin",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Send, read, and search Gmail messages via the Gmail API",
   "author": "co-assistant",
   "requiredCredentials": [

package/plugins/gmail/tools.ts

@@ -117,7 +117,7 @@ export function createGmailTools(auth: GmailAuth, logger: Logger): ToolDefinitio
   const searchEmails: ToolDefinition = {
     name: "search_emails",
     description:
-      "Search for emails in Gmail using a query string (same syntax as the Gmail search bar)",
+      "Search for emails in Gmail. Returns metadata by default; set includeBody=true to also return full message bodies (avoids needing separate read_email calls).",
     parameters: z.object({
       /** Gmail search query (e.g. "from:alice subject:meeting"). */
       query: z.string().describe("Gmail search query"),
@@ -130,13 +130,21 @@ export function createGmailTools(auth: GmailAuth, logger: Logger): ToolDefinitio
         .optional()
         .default(10)
         .describe("Maximum number of results to return"),
+      /** When true, fetches full message bodies inline. Slower per message but
+       *  eliminates the need for separate read_email calls. */
+      includeBody: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Include full message body in results"),
     }),
 
     handler: async (args) => {
       try {
         const query = args.query as string;
         const maxResults = (args.maxResults as number | undefined) ?? 10;
-        logger.debug({ query, maxResults }, "search_emails called");
+        const includeBody = (args.includeBody as boolean | undefined) ?? false;
+        logger.debug({ query, maxResults, includeBody }, "search_emails called");
 
         // Step 1 — List message IDs matching the query.
         const params = new URLSearchParams({
@@ -162,32 +170,47 @@ export function createGmailTools(auth: GmailAuth, logger: Logger): ToolDefinitio
           return "No emails found matching that query.";
         }
 
-        // Step 2 — Fetch each message's metadata (Subject, From, Date, snippet).
+        // Step 2 — Fetch each message. Use "full" format when body is
+        // requested, otherwise "metadata" for a lighter response.
+        const format = includeBody ? "full" : "metadata";
         const headers = await authHeaders(auth);
         const results = await Promise.all(
           listData.messages.map(async (msg) => {
-            const msgRes = await fetch(
-              `${GMAIL_API}/messages/${msg.id}?format=metadata&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=Date`,
-              { headers },
-            );
+            const url = includeBody
+              ? `${GMAIL_API}/messages/${msg.id}?format=${format}`
+              : `${GMAIL_API}/messages/${msg.id}?format=${format}&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=Date`;
+            const msgRes = await fetch(url, { headers });
 
             if (!msgRes.ok) {
-              return { id: msg.id, error: `Failed to fetch (${msgRes.status})` };
+              return { id: msg.id, threadId: msg.threadId, error: `Failed to fetch (${msgRes.status})` };
             }
 
             const msgData = (await msgRes.json()) as {
               id: string;
+              threadId: string;
               snippet: string;
-              payload: { headers: Array<{ name: string; value: string }> };
+              payload: {
+                headers: Array<{ name: string; value: string }>;
+                body?: { data?: string };
+                parts?: Array<Record<string, unknown>>;
+                mimeType?: string;
+              };
             };
 
-            return {
+            const result: Record<string, unknown> = {
               id: msgData.id,
+              threadId: msgData.threadId,
               subject: getHeader(msgData.payload.headers, "Subject"),
               from: getHeader(msgData.payload.headers, "From"),
               date: getHeader(msgData.payload.headers, "Date"),
               snippet: msgData.snippet,
             };
+
+            if (includeBody) {
+              result.body = extractBody(msgData.payload as Record<string, unknown>);
+            }
+
+            return result;
           }),
         );
 
@@ -332,5 +355,211 @@ export function createGmailTools(auth: GmailAuth, logger: Logger): ToolDefinitio
     },
   };
 
-  return [searchEmails, readEmail, sendEmail];
+  // -----------------------------------------------------------------------
+  // get_thread
+  // -----------------------------------------------------------------------
+  const getThread: ToolDefinition = {
+    name: "get_thread",
+    description:
+      "Get all messages in a Gmail thread (including your sent replies). " +
+      "Use this to check if you already replied to a conversation before suggesting a new reply.",
+    parameters: z.object({
+      /** The Gmail thread ID (returned by search_emails or read_email). */
+      threadId: z.string().describe("Gmail thread ID"),
+    }),
+
+    handler: async (args) => {
+      try {
+        const threadId = args.threadId as string;
+        logger.debug({ threadId }, "get_thread called");
+
+        const res = await fetch(
+          `${GMAIL_API}/threads/${threadId}?format=metadata` +
+            "&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=To&metadataHeaders=Date",
+          { headers: await authHeaders(auth) },
+        );
+
+        if (!res.ok) {
+          const errText = await res.text();
+          logger.error({ status: res.status, errText }, "Gmail get_thread failed");
+          return `Error getting thread (${res.status}): ${errText}`;
+        }
+
+        const data = (await res.json()) as {
+          id: string;
+          messages: Array<{
+            id: string;
+            labelIds: string[];
+            snippet: string;
+            payload: { headers: Array<{ name: string; value: string }> };
+          }>;
+        };
+
+        const messages = data.messages.map((msg) => ({
+          id: msg.id,
+          from: getHeader(msg.payload.headers, "From"),
+          to: getHeader(msg.payload.headers, "To"),
+          date: getHeader(msg.payload.headers, "Date"),
+          snippet: msg.snippet,
+          isSent: msg.labelIds?.includes("SENT") ?? false,
+        }));
+
+        return {
+          threadId: data.id,
+          messageCount: messages.length,
+          messages,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error({ error: message }, "get_thread error");
+        return `Error getting thread: ${message}`;
+      }
+    },
+  };
+
+  // -----------------------------------------------------------------------
+  // search_threads  (single-call inbox analysis)
+  // -----------------------------------------------------------------------
+  const searchThreads: ToolDefinition = {
+    name: "search_threads",
+    description:
+      "Search Gmail and return results grouped by thread. Each thread includes " +
+      "ALL messages (including your sent replies) with isSent flags, so you can " +
+      "tell at a glance whether you already replied. Ideal for inbox review — " +
+      "returns everything in a single call.",
+    parameters: z.object({
+      /** Gmail search query (e.g. "in:inbox", "from:alice"). */
+      query: z.string().describe("Gmail search query"),
+      /** Maximum threads to return (default 5, max 20). */
+      maxThreads: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .optional()
+        .default(5)
+        .describe("Maximum number of threads to return"),
+      /** When true, includes the full decoded body of the latest message in
+       *  each thread. When false, only snippets are returned. */
+      includeLatestBody: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Include full body of the latest message per thread"),
+    }),
+
+    handler: async (args) => {
+      try {
+        const query = args.query as string;
+        const maxThreads = (args.maxThreads as number | undefined) ?? 5;
+        const includeLatestBody = (args.includeLatestBody as boolean | undefined) ?? false;
+        logger.debug({ query, maxThreads, includeLatestBody }, "search_threads called");
+
+        // Step 1 — List thread IDs matching the query.
+        const params = new URLSearchParams({
+          q: query,
+          maxResults: String(maxThreads),
+        });
+        const listRes = await fetch(`${GMAIL_API}/threads?${params}`, {
+          headers: await authHeaders(auth),
+        });
+
+        if (!listRes.ok) {
+          const errText = await listRes.text();
+          logger.error({ status: listRes.status, errText }, "Gmail threads search failed");
+          return `Error searching threads (${listRes.status}): ${errText}`;
+        }
+
+        const listData = (await listRes.json()) as {
+          threads?: Array<{ id: string; snippet: string }>;
+          resultSizeEstimate?: number;
+        };
+
+        if (!listData.threads?.length) {
+          return { threadCount: 0, threads: [] };
+        }
+
+        // Step 2 — Fetch each thread. Use "full" format for the latest
+        // message body when requested, "metadata" otherwise.
+        const format = includeLatestBody ? "full" : "metadata";
+        const headers = await authHeaders(auth);
+        const threads = await Promise.all(
+          listData.threads.map(async (t) => {
+            const url =
+              `${GMAIL_API}/threads/${t.id}?format=${format}` +
+              "&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=To&metadataHeaders=Date";
+            const res = await fetch(url, { headers });
+
+            if (!res.ok) {
+              return { threadId: t.id, error: `Failed to fetch (${res.status})` };
+            }
+
+            const data = (await res.json()) as {
+              id: string;
+              messages: Array<{
+                id: string;
+                labelIds: string[];
+                snippet: string;
+                payload: {
+                  headers: Array<{ name: string; value: string }>;
+                  body?: { data?: string };
+                  parts?: Array<Record<string, unknown>>;
+                  mimeType?: string;
+                };
+              }>;
+            };
+
+            // Build a compact summary for each message in the thread.
+            const messages = data.messages.map((msg) => {
+              const result: Record<string, unknown> = {
+                id: msg.id,
+                from: getHeader(msg.payload.headers, "From"),
+                to: getHeader(msg.payload.headers, "To"),
+                date: getHeader(msg.payload.headers, "Date"),
+                snippet: msg.snippet,
+                isSent: msg.labelIds?.includes("SENT") ?? false,
+              };
+              return result;
+            });
+
+            // The last message in the array is the most recent.
+            const latest = data.messages[data.messages.length - 1];
+            const lastIsSent = latest?.labelIds?.includes("SENT") ?? false;
+            const subject = getHeader(
+              data.messages[0].payload.headers,
+              "Subject",
+            );
+
+            const thread: Record<string, unknown> = {
+              threadId: data.id,
+              subject,
+              messageCount: messages.length,
+              lastMessageIsSent: lastIsSent,
+              messages,
+            };
+
+            // Only decode the body for the latest message when requested.
+            if (includeLatestBody && latest) {
+              thread.latestBody = extractBody(
+                latest.payload as Record<string, unknown>,
+              );
+            }
+
+            return thread;
+          }),
+        );
+
+        return {
+          threadCount: threads.length,
+          threads,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error({ error: message }, "search_threads error");
+        return `Error searching threads: ${message}`;
+      }
+    },
+  };
+
+  return [searchEmails, readEmail, sendEmail, getThread, searchThreads];
 }