Skip to content

Commit 960c614

Browse files
KrisBraunclaude
andcommitted
twister: add NoteWriteBackResult + sync baseline, roll out across bidirectional connectors
Plot-authored notes pushed to external systems that store content in lossier formats (plain-text comments APIs, ADF, sanitized HTML) were losing their markdown on round-trip: the connector's next sync-in re-ingested the external's plain-text version and overwrote Plot's original. Fix: track a per-note external-content baseline so sync-in can tell "unchanged, preserve Plot" from "externally edited, overwrite Plot". SDK: - New NoteWriteBackResult type: { key?, externalContent? }. Widen onNoteCreated / onNoteUpdated to accept it. Plain-string return still works. The hash is over content-string only — write-back and sync-in don't need to agree on a contentType label to match. Docs: - connectors/AGENTS.md: rewrite "Bidirectional sync", add "Sync baseline preservation" subsection stating the externalContent-must-equal-sync-in contract and failure modes; extend checklist + pitfalls; flag google-drive as the canonical reference in the examples table. - twister/docs/BUILDING_CONNECTORS.md: new "Bidirectional Note Sync" section. - twister/docs/SYNC_STRATEGIES.md: modernize the two-way sync example. - twister/docs/MULTI_USER_AUTH.md: update onNoteCreated example. - twister/cli/templates/AGENTS.template.md: update new-twist boilerplate. Connectors (11): - Google Drive (reference impl; comments + replies, with update endpoints). - Slack: chat.update added; shared formatSlackText for consistent baseline. - Google Chat: messages.patch added; keeps existing reaction-sync path. - MS Teams: PATCH on chats and channels/replies; dropped dead sent:* tracking. - Gmail: key-only baseline (no edit API for sent mail; first sync-in establishes baseline organically). - Linear: commentUpdate added; fixes pre-existing bug where onNoteCreated dropped the comment-{id} key entirely. - Jira: issueComments.updateComment added; same pre-existing key-dropping fix. Baseline uses extractTextFromADF so it matches sync-in's stored content. - GitHub: PATCH on issue/PR comments; shared updateIssueComment helper. - Todoist: POST /comments/{id} added; removes the saveLink hack that was previously needed to smuggle the comment key back. - Attio: baseline only (no PATCH on Attio notes); builds matching **title**\n\ncontent shape that sync-in reconstructs. - Airtable: PATCH on comments; baseline applies translateMentionsInbound so it matches sync-in's stored form. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 81ac72d commit 960c614

27 files changed

Lines changed: 1011 additions & 217 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@plotday/twister": minor
3+
---
4+
5+
Added: `NoteWriteBackResult` type and widened `onNoteCreated`/`onNoteUpdated` return types to accept it. Connectors performing two-way note sync can now return `{ key?, externalContent? }` so the runtime tracks a sync baseline of what the external system stored, preventing the next sync-in from clobbering Plot's (potentially richer-markdown) version with the round-tripped plain text. Back-compat preserved: `onNoteCreated` still accepts a plain string return.

‎connectors/AGENTS.md‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ Populating `thread.contacts` with recipients does NOT automatically admit them.
238238

239239
## Note key conventions
240240

241-
`note.key` enables note-level upserts:
241+
`note.key` enables note-level upserts AND is the only way the runtime can correlate a Plot-authored note with its external counterpart for baseline preservation (see "Sync baseline preservation" above). Bidirectional connectors must assign keys on write-back.
242242

243243
```
244244
"description" — main body
@@ -331,18 +331,60 @@ async updateIssue(activity: Activity): Promise<void> {
331331
await client.updateItem(externalId, { title: activity.title, done: /* ... */ });
332332
}
333333

334-
// Post a comment; return note key so future syncs can dedupe
335-
async addIssueComment(meta: ActivityMeta, body: string, noteId?: string): Promise<string | void> {
336-
const client = await this.getClient(meta.resourceId as string);
337-
const comment = await client.createComment(meta.externalId as string, { body });
338-
if (comment?.id) return `comment-${comment.id}`;
334+
// Post a comment. Return a NoteWriteBackResult with externalContent so the
335+
// runtime can establish a sync baseline (see "Sync baseline preservation"
336+
// below). Returning just a string still works, but without a baseline the
337+
// next sync-in will overwrite Plot's (possibly richer-markdown) content
338+
// with the round-tripped plain text the external system stored.
339+
async onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
340+
const client = await this.getClient(thread.meta?.resourceId as string);
341+
const comment = await client.createComment(thread.meta?.externalId as string, { body: note.content ?? "" });
342+
if (!comment?.id) return;
343+
return {
344+
key: `comment-${comment.id}`,
345+
externalContent: comment.body, // what the external system NOW STORES
346+
};
347+
}
348+
349+
// Push a local edit back to the external system. `note.key` identifies the
350+
// target; refresh the baseline from the response so the next sync-in
351+
// recognises the round-trip and preserves Plot's edited content.
352+
async onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
353+
if (!note.key?.startsWith("comment-")) return;
354+
const commentId = note.key.slice("comment-".length);
355+
const client = await this.getClient(thread.meta?.resourceId as string);
356+
const updated = await client.updateComment(commentId, { body: note.content ?? "" });
357+
return { externalContent: updated.body };
339358
}
340359
```
341360

342361
**Loop prevention** (in the twist, not the connector): `if (note.author.type === ActorType.Twist) return;`
343362

344363
**`handleReplies`**: bidirectional connectors must set `static readonly handleReplies = true` to enable @-mentions on replies. Read-only connectors should NOT.
345364

365+
### Sync baseline preservation (required for any note round-trip)
366+
367+
When Plot pushes a note to an external system that stores content in a lossier format than Plot does (e.g. plain-text comments APIs, ADF, HTML that gets sanitised), the external's version re-ingested on the next sync would overwrite Plot's original content with the round-tripped form — `1.` → `1\.`, `[name]` → `\[name\]`, etc. To prevent this, the runtime tracks a per-note "external baseline" hash in `note.external_content_hash`:
368+
369+
- **Write-back (`onNoteCreated` / `onNoteUpdated`) returns `NoteWriteBackResult`** with `externalContent` set to what the external system now stores. The runtime hashes this and stores it as the note's baseline. (The hash is over the content string only — no contentType prefix — so write-back and sync-in don't need to agree on a contentType label to match.)
370+
- **Sync-in** computes the same hash on each incoming `NewNote.content`. Match → preserve Plot's stored content (skip overwrite). Mismatch → external was edited, overwrite.
371+
372+
The hard contract:
373+
374+
> **`externalContent` must exactly equal the `NewNote.content` string your sync-in path will emit for this note on re-ingest.**
375+
376+
If your sync-in runs incoming comment bodies through a transform (e.g. Airtable's `translateMentionsInbound`, Jira's `extractTextFromADF`), apply the same transform to the write-back response before returning it. Pick the value by looking at the sync-in `build*Note` function and returning exactly what ends up in `content`.
377+
378+
For systems that return the stored representation on write (Drive, GitHub, Linear, Slack `chat.postMessage`), use the response directly. For systems that don't (Gmail `messages.send`), either fetch the stored form with an extra API call or skip `externalContent` — the first sync-in after the write will organically establish the baseline. Document the tradeoff.
379+
380+
**Failure modes you must avoid:**
381+
382+
- Returning `externalContent` that differs from what sync-in will produce → every sync-in clobbers Plot's content.
383+
- Not setting `handleReplies = true` → dispatch never reaches `onNoteCreated`.
384+
- Calling `integrations.saveLink()` inside `onNoteCreated` to propagate the key → no longer needed (runtime now does it). Remove any such workaround.
385+
386+
**Legacy:** `onNoteCreated` may still return a plain `string` — treated as `{ key }` with no baseline. Don't use this shape in new connectors.
387+
346388
### Creating new items from Plot (`onCreateLink`)
347389

348390
Opt a link type in by marking one status with `createDefault: true`:
@@ -430,6 +472,8 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
430472
- [ ] Extend `Connector<YourConnector>`; declare `PROVIDER`, `SCOPES`, `Options` (static + `declare readonly`)
431473
- [ ] `build()` declares Integrations, Network, Callbacks, Tasks (plus GoogleContacts if applicable)
432474
- [ ] Set `handleReplies = true` only if bidirectional
475+
- [ ] For bidirectional note sync: `onNoteCreated` / `onNoteUpdated` return `NoteWriteBackResult` with `externalContent` matching what sync-in will emit for this note — no `Promise<string | void>` in new connectors
476+
- [ ] For bidirectional note sync: implement `onNoteUpdated` if the external supports editing (document the gap if it doesn't)
433477
- [ ] `onChannelEnabled` uses `runTask()` (NOT `run()`) for webhook setup and initial sync — blocks HTTP response otherwise
434478
- [ ] Convert parent callbacks to tokens with `createFromParent()`; store via `this.set()`; retrieve with `this.get<Callback>()`
435479
- [ ] Never pass functions, RPC stubs, or `undefined` to `this.callback()` — use `null`
@@ -465,6 +509,9 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
465509
15. `this.run()` in `onChannelEnabled` → blocks HTTP response until full sync completes; always `runTask()`.
466510
16. Calling `integrations.saveLink()` inside `onCreateLink` → duplicate thread; just return the link.
467511
17. Implementing `onCreateLink` without `createDefault: true` on a status → "Create new X" entry never appears.
512+
18. Returning a bare `string` (key only) from `onNoteCreated` when the external stores content lossily (plain-text comments APIs, ADF, sanitised HTML) → next sync-in clobbers Plot's content with the round-tripped form (e.g. `1.` → `1\.`). Return a `NoteWriteBackResult` with `externalContent` matching sync-in's shape instead.
513+
19. Returning `externalContent` that doesn't match what sync-in emits for the same note (e.g. post-write raw HTML when sync-in extracts plain text; pre-translation mentions when sync-in translates them) → baseline hash always mismatches and every sync clobbers. Inspect the sync-in `build*Note` path and return exactly what it produces.
514+
20. Calling `integrations.saveLink()` inside `onNoteCreated` to set the note's `key` → legacy workaround, no longer needed. The runtime sets `key` automatically from the `NoteWriteBackResult` return.
468515

469516
## Examples
470517

@@ -474,7 +521,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
474521
| `google-calendar/` | CalendarConnector | Recurring events; RSVP write-back; watch renewal; shared Google auth |
475522
| `slack/` | MessagingConnector | Team-sharded webhooks; thread model |
476523
| `gmail/` | MessagingConnector | PubSub webhooks; HTML contentType; callback-arg `initialSync` |
477-
| `google-drive/` | DocumentConnector | Document comments; reply threading; file watching |
524+
| `google-drive/` | DocumentConnector | Document comments; reply threading; file watching; canonical `NoteWriteBackResult` + `onNoteUpdated` example |
478525
| `jira/` | ProjectConnector | Immutable vs mutable ids; comment metadata dedup |
479526
| `asana/` | ProjectConnector | HMAC webhook verification; section-based projects |
480527
| `outlook-calendar/` | CalendarConnector | Microsoft Graph; subscription management |

‎connectors/airtable/src/airtable-api.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,20 @@ export class AirtableAPI {
310310
);
311311
}
312312

313+
async updateComment(
314+
baseId: string,
315+
tableId: string,
316+
recordId: string,
317+
commentId: string,
318+
body: { text: string }
319+
): Promise<AirtableComment> {
320+
return this.req<AirtableComment>(
321+
"PATCH",
322+
`/v0/${baseId}/${tableId}/${recordId}/comments/${commentId}`,
323+
body
324+
);
325+
}
326+
313327
async createWebhook(
314328
baseId: string,
315329
notificationUrl: string,

‎connectors/airtable/src/airtable.ts‎

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import {
44
type Link,
55
type NewLinkWithNotes,
66
type Note,
7+
type NoteWriteBackResult,
78
type Thread,
89
type ThreadMeta,
910
} from "@plotday/twister";
@@ -1041,7 +1042,10 @@ export class Airtable extends Connector<Airtable> {
10411042
}
10421043
}
10431044

1044-
async onNoteCreated(note: Note, thread: Thread): Promise<string | void> {
1045+
async onNoteCreated(
1046+
note: Note,
1047+
thread: Thread
1048+
): Promise<NoteWriteBackResult | void> {
10451049
const meta = (thread.meta ?? {}) as ThreadMeta;
10461050
const baseId = meta.airtableBaseId as string | undefined;
10471051
const tableId = meta.airtableTableId as string | undefined;
@@ -1057,12 +1061,64 @@ export class Airtable extends Connector<Airtable> {
10571061
const comment = await api.createComment(baseId, tableId, recordId, {
10581062
text: this.translateMentionsOutbound(text),
10591063
});
1060-
if (comment?.id) return `comment-${comment.id}`;
1064+
if (comment?.id) {
1065+
// Sync-in stores comments via translateMentionsInbound (@[token] →
1066+
// @Name). Match that form here so the baseline hash aligns with
1067+
// what recordToLink/listComments will produce on the next pass —
1068+
// otherwise the round-tripped comment would clobber the Plot note
1069+
// with its lossy Airtable echo.
1070+
return {
1071+
key: `comment-${comment.id}`,
1072+
externalContent: this.translateMentionsInbound(comment),
1073+
};
1074+
}
10611075
} catch (error) {
10621076
console.warn("Failed to post Airtable comment:", error);
10631077
}
10641078
}
10651079

1080+
/**
1081+
* Push an edit to an existing Airtable comment and refresh the sync
1082+
* baseline from the updated text. Note keys are `comment-<airtableId>`
1083+
* (see {@link recordToLink}); non-comment keys (e.g. the synthetic
1084+
* "description" note) are not editable on the Airtable side.
1085+
*/
1086+
async onNoteUpdated(
1087+
note: Note,
1088+
thread: Thread
1089+
): Promise<NoteWriteBackResult | void> {
1090+
if (!note.key) return;
1091+
const commentMatch = note.key.match(/^comment-(.+)$/);
1092+
if (!commentMatch) return;
1093+
const commentId = commentMatch[1];
1094+
1095+
const meta = (thread.meta ?? {}) as ThreadMeta;
1096+
const baseId = meta.airtableBaseId as string | undefined;
1097+
const tableId = meta.airtableTableId as string | undefined;
1098+
const recordId = meta.airtableRecordId as string | undefined;
1099+
if (!baseId || !tableId || !recordId) return;
1100+
1101+
const text = (note.content ?? "").trim();
1102+
if (text.length === 0) return;
1103+
1104+
const api = await this.getAPI(baseId);
1105+
if (!api) return;
1106+
try {
1107+
const comment = await api.updateComment(
1108+
baseId,
1109+
tableId,
1110+
recordId,
1111+
commentId,
1112+
{ text: this.translateMentionsOutbound(text) }
1113+
);
1114+
return {
1115+
externalContent: this.translateMentionsInbound(comment),
1116+
};
1117+
} catch (error) {
1118+
console.warn("Failed to update Airtable comment:", error);
1119+
}
1120+
}
1121+
10661122
/**
10671123
* Convert `@email@example.com` or `@[email@example.com]` in Plot note
10681124
* content to Airtable's mention syntax `@[email@example.com]`. Airtable

‎connectors/attio/src/attio.ts‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import {
22
type Link,
33
type NewLinkWithNotes,
44
type Note,
5+
type NoteWriteBackResult,
56
type Thread,
67
} from "@plotday/twister";
78
import type { NewContact } from "@plotday/twister/plot";
@@ -654,14 +655,57 @@ export class Attio extends Connector<Attio> {
654655
}
655656
}
656657

657-
/** Write back notes/comments to Attio as notes on the record. */
658-
async onNoteCreated(note: Note, thread: Thread): Promise<void> {
658+
/**
659+
* Write back notes/comments to Attio as notes on the record.
660+
*
661+
* Returns a {@link NoteWriteBackResult} so the runtime can (a) key the
662+
* Plot note for future upserts and (b) hash the external representation
663+
* as the sync baseline. The baseline matches the exact string the
664+
* sync-in path ({@link saveNoteOnParent}) will build on the next pass:
665+
* Attio falls back to `title = "Comment from Plot"` when we send an
666+
* empty title, so sync-in reconstructs the note as
667+
* `**Comment from Plot**\n\n{content_plaintext}`.
668+
*/
669+
async onNoteCreated(
670+
note: Note,
671+
thread: Thread
672+
): Promise<NoteWriteBackResult | void> {
659673
const recordId = thread.meta?.attioRecordId as string | undefined;
660674
const objectSlug = thread.meta?.attioObjectSlug as string | undefined;
661675
if (!recordId || !objectSlug) return;
662676

677+
const content = note.content ?? "";
663678
const api = this.getAPI();
664-
await api.createNote(objectSlug, recordId, "", note.content ?? "");
679+
const result = await api.createNote(objectSlug, recordId, "", content);
680+
const noteId = result?.data?.id?.note_id;
681+
if (!noteId) return;
682+
683+
// Must match the form saveNoteOnParent will reconstruct on sync-in.
684+
// saveNoteOnParent uses contentType default (= "markdown") — keep that
685+
// in sync here so the baseline hash matches.
686+
const externalContent = `**Comment from Plot**\n\n${content}`;
687+
688+
return {
689+
key: `note-${noteId}`,
690+
externalContent,
691+
};
692+
}
693+
694+
/**
695+
* Attio's public REST API exposes only create/get/list/delete for notes —
696+
* there is no update endpoint (verified against
697+
* https://docs.attio.com/rest-api/endpoint-reference/notes). Without a
698+
* stable update path we can't safely rewrite an existing note (delete +
699+
* recreate would change the note id, breaking the `note-<id>` key that
700+
* the next sync pass uses for upsert). Leaving this as a no-op means
701+
* edits to Plot notes are not written back; the next full sync will
702+
* still reflect any server-side edits from the Attio side.
703+
*/
704+
async onNoteUpdated(
705+
_note: Note,
706+
_thread: Thread
707+
): Promise<NoteWriteBackResult | void> {
708+
return;
665709
}
666710

667711
}

‎connectors/github/src/github.ts‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import {
22
type Link,
33
type NewLinkWithNotes,
44
type Note,
5+
type NoteWriteBackResult,
56
Connector,
67
type Thread,
78
type ToolBuilder,
@@ -35,6 +36,7 @@ import {
3536
handleIssueCommentWebhook,
3637
updateIssue,
3738
addIssueComment,
39+
updateIssueComment,
3840
} from "./issue-sync";
3941

4042
// ---------- Exported types (used by pr-sync.ts and issue-sync.ts) ----------
@@ -369,16 +371,58 @@ export class GitHub extends Connector<GitHub> {
369371

370372
/**
371373
* Called when a note is created on a thread owned by this source.
374+
*
375+
* Returns a {@link NoteWriteBackResult} so the runtime sets the note's
376+
* key to `comment-<githubCommentId>` (matching what sync-in uses) and
377+
* records the external sync baseline. GitHub stores comment bodies as
378+
* markdown and returns the stored body verbatim, so the hashed baseline
379+
* matches what the next incremental sync will surface.
372380
*/
373-
async onNoteCreated(note: Note, thread: Thread): Promise<void> {
381+
async onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
374382
const meta = thread.meta ?? {};
383+
const body = note.content ?? "";
375384
if (meta.prNumber) {
376-
await addPRComment(this, meta, note.content ?? "");
385+
const result = await addPRComment(this, meta, body);
386+
if (!result) return;
387+
return {
388+
key: `comment-${result.id}`,
389+
externalContent: result.body,
390+
};
377391
} else if (meta.issueNumber) {
378-
await addIssueComment(this, meta, note.content ?? "");
392+
const result = await addIssueComment(this, meta, body);
393+
if (!result) return;
394+
return {
395+
key: `comment-${result.id}`,
396+
externalContent: result.body,
397+
};
379398
}
380399
}
381400

401+
/**
402+
* Called when a Plot user edits an existing note on a GitHub-owned thread.
403+
*
404+
* Pushes the new content to the corresponding GitHub comment (PR and
405+
* issue conversation comments live under the same endpoint) and refreshes
406+
* the sync baseline from GitHub's stored markdown body.
407+
*/
408+
async onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
409+
const meta = thread.meta ?? {};
410+
if (!note.key) return;
411+
if (!meta.prNumber && !meta.issueNumber) return;
412+
413+
const match = note.key.match(/^comment-(\d+)$/);
414+
if (!match) return;
415+
const commentId = Number(match[1]);
416+
if (!Number.isFinite(commentId)) return;
417+
418+
const body = note.content ?? "";
419+
const result = await updateIssueComment(this, meta, commentId, body);
420+
if (!result) return;
421+
return {
422+
externalContent: result.body,
423+
};
424+
}
425+
382426
// ---------- Webhook ----------
383427

384428
/**

0 commit comments

Comments
 (0)