Add thread todo sync, pass Thread to source callbacks, and Gmail star↔todo sync

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: KrisBraun

sources/github/src/github.ts

@@ -3,7 +3,7 @@ import {
   type NewLinkWithNotes,
   type Note,
   Source,
-  type ThreadMeta,
+  type Thread,
   type ToolBuilder,
 } from "@plotday/twister";
 import type { NewContact } from "@plotday/twister/plot";
@@ -350,7 +350,8 @@ export class GitHub extends Source<GitHub> {
   /**
    * Called when a note is created on a thread owned by this source.
    */
-  async onNoteCreated(note: Note, meta: ThreadMeta): Promise<void> {
+  async onNoteCreated(note: Note, thread: Thread): Promise<void> {
+    const meta = thread.meta ?? {};
     if (meta.prNumber) {
       await addPRComment(this, meta, note.content ?? "");
     } else if (meta.issueNumber) {

sources/gmail/src/gmail-api.ts

@@ -204,6 +204,13 @@ export class GmailApi {
     });
   }
 
+  /**
+   * Checks if any message in a Gmail thread has the STARRED label.
+   */
+  static isStarred(thread: GmailThread): boolean {
+    return thread.messages?.some(m => m.labelIds?.includes("STARRED")) ?? false;
+  }
+
   public async getHistory(
     startHistoryId: string,
     labelId?: string,

sources/gmail/src/gmail.ts

@@ -1,5 +1,5 @@
 import { Source, type ToolBuilder } from "@plotday/twister";
-import type { Actor, Note, Thread, ThreadMeta } from "@plotday/twister/plot";
+import type { Actor, ActorId, Note, Thread } from "@plotday/twister/plot";
 import {
   AuthProvider,
   type AuthToken,
@@ -70,6 +70,10 @@ export class Gmail extends Source<Gmail> {
     };
   }
 
+  override async activate(context: { auth: Authorization; actor: Actor }): Promise<void> {
+    await this.set("auth_actor_id", context.actor.id);
+  }
+
   async getChannels(
     _auth: Authorization,
     token: AuthToken
@@ -326,14 +330,40 @@ export class Gmail extends Source<Gmail> {
 
         // Save link directly via integrations
         await this.tools.integrations.saveLink(plotThread);
+
+        // Star ↔ todo sync: detect star changes and update Plot todo status
+        const isStarred = GmailApi.isStarred(thread);
+        const wasStarred = await this.get<boolean>(`starred:${thread.id}`);
+
+        if (isStarred !== !!wasStarred) {
+          // Skip if this change originated from Plot todo writeback
+          if (await this.get(`skip_star_sync:${thread.id}`)) {
+            await this.clear(`skip_star_sync:${thread.id}`);
+          } else {
+            const actorId = await this.get<ActorId>("auth_actor_id");
+            // Use the canonical Gmail thread URL as the source identifier
+            const sourceUrl = `https://mail.google.com/mail/u/0/#inbox/${thread.id}`;
+            if (actorId) {
+              await this.tools.integrations.setThreadToDo(
+                sourceUrl,
+                actorId,
+                isStarred
+              );
+              // Prevent the onThreadToDo callback from echoing back
+              await this.set(`skip_todo_writeback:${thread.id}`, true);
+            }
+          }
+          await this.set(`starred:${thread.id}`, isStarred);
+        }
       } catch (error) {
         console.error(`Failed to process Gmail thread ${thread.id}:`, error);
         // Continue processing other threads
       }
     }
   }
 
-  async onNoteCreated(note: Note, meta: ThreadMeta): Promise<void> {
+  async onNoteCreated(note: Note, thread: Thread): Promise<void> {
+    const meta = thread.meta ?? {};
     const channelId = (meta.channelId ?? meta.syncableId) as string;
     if (!channelId) {
       console.error("No channelId in meta for Gmail reply");
@@ -430,11 +460,11 @@ export class Gmail extends Source<Gmail> {
   }
 
   async onThreadRead(
-    _thread: Thread,
+    thread: Thread,
     _actor: Actor,
-    unread: boolean,
-    meta: ThreadMeta
+    unread: boolean
   ): Promise<void> {
+    const meta = thread.meta ?? {};
     const channelId = (meta.channelId ?? meta.syncableId) as string;
     if (!channelId) return;
 
@@ -450,6 +480,34 @@ export class Gmail extends Source<Gmail> {
     }
   }
 
+  async onThreadToDo(
+    thread: Thread,
+    _actor: Actor,
+    todo: boolean,
+    _options: { date?: Date }
+  ): Promise<void> {
+    const meta = thread.meta ?? {};
+    const threadId = meta.threadId as string;
+    const channelId = (meta.channelId ?? meta.syncableId) as string;
+    if (!threadId || !channelId) return;
+
+    // Loop prevention: skip if this change originated from Gmail star sync
+    if (await this.get(`skip_todo_writeback:${threadId}`)) {
+      await this.clear(`skip_todo_writeback:${threadId}`);
+      return;
+    }
+
+    const api = await this.getApi(channelId);
+    if (todo) {
+      await api.modifyThread(threadId, ["STARRED"]);
+    } else {
+      await api.modifyThread(threadId, undefined, ["STARRED"]);
+    }
+
+    // Prevent the Gmail webhook from echoing this change back
+    await this.set(`skip_star_sync:${threadId}`, true);
+  }
+
   async onGmailWebhook(
     request: WebhookRequest,
     channelId: string

twister/src/plot.ts

@@ -373,6 +373,8 @@ type ThreadFields = ThreadCommon & {
   priority: Priority;
   /** The schedule associated with this thread, if any */
   schedule?: Schedule;
+  /** Source-specific metadata from the thread's link, populated on callbacks */
+  meta?: ThreadMeta;
 };
 
 export type Thread = ThreadFields;

twister/src/source.ts

@@ -1,4 +1,4 @@
-import { type Actor, type Link, type Note, type Thread, type ThreadMeta } from "./plot";
+import { type Actor, type Link, type Note, type Thread } from "./plot";
 import {
   type AuthProvider,
   type AuthToken,
@@ -127,10 +127,10 @@ export abstract class Source<TSelf> extends Twist<TSelf> {
    * (e.g., adding a comment to a Linear issue).
    *
    * @param note - The created note
-   * @param meta - Metadata from the thread's link
+   * @param thread - The thread the note belongs to (includes thread.meta with source-specific data)
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  onNoteCreated(note: Note, meta: ThreadMeta): Promise<void> {
+  onNoteCreated(note: Note, thread: Thread): Promise<void> {
     return Promise.resolve();
   }
 
@@ -139,13 +139,28 @@ export abstract class Source<TSelf> extends Twist<TSelf> {
    * Override to write back read status to the external service
    * (e.g., marking an email as read in Gmail).
    *
-   * @param thread - The thread that was read/unread
+   * @param thread - The thread that was read/unread (includes thread.meta with source-specific data)
    * @param actor - The user who performed the action
    * @param unread - false when marked as read, true when marked as unread
-   * @param meta - Metadata from the thread's link (contains channelId, threadId, etc.)
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  onThreadRead(thread: Thread, actor: Actor, unread: boolean, meta: ThreadMeta): Promise<void> {
+  onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called when a user marks or unmarks a thread as todo.
+   * Override to sync todo status to the external service
+   * (e.g., starring an email in Gmail when marked as todo).
+   *
+   * @param thread - The thread (includes thread.meta with source-specific data)
+   * @param actor - The user who changed the todo status
+   * @param todo - true when marked as todo, false when done or removed
+   * @param options - Additional context
+   * @param options.date - The todo date (when todo=true)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {
     return Promise.resolve();
   }
 

twister/src/tools/integrations.ts

@@ -180,6 +180,23 @@ export abstract class Integrations extends ITool {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;
 
+  /**
+   * Sets or clears todo status on a thread owned by this source.
+   *
+   * @param source - The link source URL identifying the thread
+   * @param actorId - The user to set the todo for
+   * @param todo - true to mark as todo, false to clear/complete
+   * @param options - Additional options
+   * @param options.date - The todo date (when todo=true). Defaults to today.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract setThreadToDo(
+    source: string,
+    actorId: ActorId,
+    todo: boolean,
+    options?: { date?: Date | string }
+  ): Promise<void>;
+
 }
 
 /**