You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 960c614
Browse filesBrowse the repository at this point in the historyBrowse files
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>
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.
Copy file name to clipboardExpand all lines: connectors/AGENTS.md
+54-7Lines changed: 54 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -238,7 +238,7 @@ Populating `thread.contacts` with recipients does NOT automatically admit them.
238
238
239
239
## Note key conventions
240
240
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.
**Loop prevention** (in the twist, not the connector): `if (note.author.type === ActorType.Twist) return;`
343
362
344
363
**`handleReplies`**: bidirectional connectors must set `static readonly handleReplies = true` to enable @-mentions on replies. Read-only connectors should NOT.
345
364
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
+
346
388
### Creating new items from Plot (`onCreateLink`)
347
389
348
390
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.
-[ ] 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)
433
477
-[ ]`onChannelEnabled` uses `runTask()` (NOT `run()`) for webhook setup and initial sync — blocks HTTP response otherwise
434
478
-[ ] Convert parent callbacks to tokens with `createFromParent()`; store via `this.set()`; retrieve with `this.get<Callback>()`
435
479
-[ ] 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.
465
509
15.`this.run()` in `onChannelEnabled` → blocks HTTP response until full sync completes; always `runTask()`.
466
510
16. Calling `integrations.saveLink()` inside `onCreateLink` → duplicate thread; just return the link.
467
511
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.
468
515
469
516
## Examples
470
517
@@ -474,7 +521,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
0 commit comments