Fix duplicate comments when commenting inside Plot

Author: KrisBraun

.changeset/bumpy-guests-design.md

@@ -0,0 +1,7 @@
+---
+"@plotday/tool-linear": patch
+"@plotday/tool-asana": patch
+"@plotday/tool-jira": patch
+---
+
+Fixed: Duplicate comments when commenting inside Plot

.changeset/old-nights-dress.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": patch
+---
+
+Added: Update Note.key when updating with id

tools/AGENTS.md

@@ -279,6 +279,7 @@ Building a tool? Follow this checklist:
 4. **❌ Forgetting to store the callback token** - Store it immediately after creating
 5. **❌ Passing undefined instead of null** - Use `null` for optional values
 6. **❌ Not breaking loops into batches** - Each execution has ~1000 request limit; use `runTask()` for fresh limits
+7. **❌ Two-way sync without metadata correlation** - When pushing Plot items to an external system, embed the Plot ID (`Activity.id` / `Note.id`) in the external item's metadata, and update `source`/`key` after creation. In webhook handlers, check metadata for the Plot ID first. This prevents duplicates from a race condition where the webhook arrives before the `source`/`key` update. See SYNC_STRATEGIES.md §6 for a full example.
 
 ---
 

tools/asana/src/asana.ts

@@ -475,16 +475,20 @@ export class Asana extends Tool<Asana> implements ProjectTool {
     authToken: string,
     meta: ActivityMeta,
     body: string
-  ): Promise<void> {
+  ): Promise<string | void> {
     const taskGid = meta.taskGid as string | undefined;
     if (!taskGid) {
       throw new Error("Asana task GID not found in activity meta");
     }
     const client = await this.getClient(authToken);
 
-    await client.tasks.addComment(taskGid, {
+    const result = await client.tasks.addComment(taskGid, {
       text: body,
     });
+
+    if (result?.gid) {
+      return `story-${result.gid}`;
+    }
   }
 
   /**

tools/jira/src/jira.ts

@@ -605,8 +605,9 @@ export class Jira extends Tool<Jira> implements ProjectTool {
   async addIssueComment(
     authToken: string,
     meta: import("@plotday/twister").ActivityMeta,
-    body: string
-  ): Promise<void> {
+    body: string,
+    noteId?: string,
+  ): Promise<string | void> {
     const issueKey = meta.issueKey as string | undefined;
     if (!issueKey) {
       throw new Error("Jira issue key not found in activity meta");
@@ -616,10 +617,15 @@ export class Jira extends Tool<Jira> implements ProjectTool {
     // Convert plain text to Atlassian Document Format (ADF)
     const adfBody = this.convertTextToADF(body);
 
-    await client.issueComments.addComment({
+    const result = await client.issueComments.addComment({
       issueIdOrKey: issueKey,
       comment: adfBody,
+      properties: noteId ? [{ key: "plotNoteId", value: noteId }] : undefined,
     });
+
+    if (result?.id) {
+      return `comment-${result.id}`;
+    }
   }
 
   /**
@@ -812,13 +818,21 @@ export class Jira extends Tool<Jira> implements ProjectTool {
         ? comment.body
         : this.extractTextFromADF(comment.body);
 
+    // Check for Plot note ID in comment properties (set when comment was created from Plot)
+    const plotNoteId = comment.properties?.find(
+      (p: any) => p.key === "plotNoteId"
+    )?.value;
+
     // Create activity update with single comment note
     const activity: NewActivityWithNotes = {
       ...(source ? { source } : {}),
       type: ActivityType.Action, // Required field (will match existing activity)
       notes: [
         {
           key: `comment-${comment.id}`,
+          // If this comment originated from Plot, identify by note ID so we update the existing note
+          // rather than creating a duplicate
+          ...(plotNoteId ? { id: plotNoteId } : {}),
           activity: source ? { source } : undefined,
           content: commentText,
           created: comment.created ? new Date(comment.created) : undefined,

tools/linear/src/linear.ts

@@ -489,17 +489,13 @@ export class Linear extends Tool<Linear> implements ProjectTool {
     if (!currentAssigneeActorId) {
       updateFields.assigneeId = null;
     } else {
-      const actors = await this.tools.plot.getActors([
-        currentAssigneeActorId,
-      ]);
+      const actors = await this.tools.plot.getActors([currentAssigneeActorId]);
       const actor = actors[0];
       const email = actor?.email;
 
       if (email) {
         // Check cache first
-        let linearUserId = await this.get<string>(
-          `linear_user:${email}`
-        );
+        let linearUserId = await this.get<string>(`linear_user:${email}`);
 
         if (!linearUserId) {
           // Query Linear for user by email
@@ -578,17 +574,22 @@ export class Linear extends Tool<Linear> implements ProjectTool {
     authToken: string,
     meta: ActivityMeta,
     body: string
-  ): Promise<void> {
+  ): Promise<string | void> {
     const issueId = meta.linearId as string | undefined;
     if (!issueId) {
       throw new Error("Linear issue ID not found in activity meta");
     }
     const client = await this.getClient(authToken);
 
-    await client.createComment({
+    const payload = await client.createComment({
       issueId,
       body,
     });
+
+    const comment = await payload.comment;
+    if (comment?.id) {
+      return `comment-${comment.id}`;
+    }
   }
 
   /**

twister/cli/templates/AGENTS.template.md

@@ -570,6 +570,43 @@ const activity: NewActivity = {
 - **Incremental sync**: New activities appear as unread, and archived state is preserved (respects user's archiving decisions)
 - **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)
 
+### Two-Way Sync: Avoiding Race Conditions
+
+When implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Activity/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.
+
+**Solution:** Embed the Plot `Activity.id` / `Note.id` in the external item's metadata when creating it, and update `Activity.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.
+
+```typescript
+async pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {
+  // Create external item with Plot ID in metadata for webhook correlation
+  const externalComment = await externalApi.createComment(externalItemId, {
+    body: note.content,
+    metadata: { plotNoteId: note.id },
+  });
+
+  // Update Note with external key AFTER creation
+  // A webhook may arrive before this completes — that's OK (see onWebhook below)
+  await this.tools.plot.updateNote({
+    id: note.id,
+    key: `comment-${externalComment.id}`,
+  });
+}
+
+async onWebhook(payload: WebhookPayload): Promise<void> {
+  const comment = payload.comment;
+
+  // Use Plot ID from metadata if present (handles race condition),
+  // otherwise fall back to upserting by activity source and key
+  await this.tools.plot.createNote({
+    ...(comment.metadata?.plotNoteId
+      ? { id: comment.metadata.plotNoteId }
+      : { activity: { source: payload.itemUrl } }),
+    key: `comment-${comment.id}`,
+    content: comment.body,
+  });
+}
+```
+
 ## Error Handling
 
 Always handle errors gracefully and communicate them to users:

twister/docs/SYNC_STRATEGIES.md

@@ -754,6 +754,45 @@ async cleanupOldMappings(): Promise<void> {
 }
 ```
 
+### 6. Avoid Race Conditions in Two-Way Sync
+
+When implementing two-way sync where items can be created in Plot and pushed to an external system (e.g. Notes becoming comments), update `Activity.source` / `Note.key` **after** creating the external item. If the external system supports setting custom metadata, include the `Activity.id` / `Note.id` in the metadata when creating the external item. Then, when processing an incoming webhook, check for the Plot ID in the metadata first and use it if present.
+
+This eliminates a race condition where a webhook for an item you're creating arrives before you've updated the Activity/Note with the external key. Without this pattern, the webhook handler won't find the item by external key and may create a duplicate.
+
+```typescript
+async pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {
+  // Create the comment in the external system, embedding the Note ID in metadata
+  const externalComment = await externalApi.createComment(externalItemId, {
+    body: note.content,
+    metadata: { plotNoteId: note.id },  // Embed Plot ID for webhook correlation
+  });
+
+  // Update the Note with the external key AFTER creation
+  // A webhook may arrive between these two steps — that's OK because
+  // the webhook handler checks metadata first (see below)
+  await this.tools.plot.updateNote({
+    id: note.id,
+    key: `comment-${externalComment.id}`,
+  });
+}
+
+async onWebhook(payload: WebhookPayload): Promise<void> {
+  const comment = payload.comment;
+
+  // Use the Plot ID from metadata if present (handles the race condition
+  // where the webhook arrives before we've set the external key on the Note),
+  // otherwise fall back to upserting by activity source and key
+  await this.tools.plot.createNote({
+    ...(comment.metadata?.plotNoteId
+      ? { id: comment.metadata.plotNoteId }
+      : { activity: { source: payload.itemUrl } }),
+    key: `comment-${comment.id}`,
+    content: comment.body,
+  });
+}
+```
+
 ## Summary
 
 - **Strategy 1** (Create Once): Simplest, no deduplication, use for one-time items

twister/src/common/projects.ts

@@ -156,11 +156,13 @@ export type ProjectTool = {
    * @param authToken - Authorization token for access
    * @param meta - Activity metadata containing the tool's issue/task identifier
    * @param body - The comment text content
-   * @returns Promise that resolves when the comment is added
+   * @param noteId - Optional Plot note ID, used by tools that support comment metadata (e.g. Jira)
+   * @returns The external comment key (e.g. "comment-123") for dedup, or void
    */
   addIssueComment?(
     authToken: string,
     meta: ActivityMeta,
-    body: string
-  ): Promise<void>;
+    body: string,
+    noteId?: string,
+  ): Promise<string | void>;
 };

twister/src/plot.ts

@@ -1059,7 +1059,7 @@ export type NewNote = Partial<
  * Type for updating existing notes.
  * Must provide either id or key to identify the note to update.
  */
-export type NoteUpdate = ({ id: Uuid } | { key: string }) &
+export type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &
   Partial<Pick<Note, "private" | "archived" | "content" | "links">> & {
     /**
      * Format of the note content. Determines how the note is processed: