Real Time CollabCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: real-time-collab
description: >-
  Multi-user collaborative editing with Yjs CRDT, SSE fast-path transport, and
  granular server-side merge. Use when adding real-time collaborative editing to
  a template, debugging sync issues, or understanding how the agent and humans
  edit documents simultaneously.
scope: dev
metadata:
  internal: true
---

# Real-Time Collaboration

## Rule

Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are
equal participants — both edit the same Y.Doc and changes merge cleanly without
conflicts. Always choose an explicit `access` mode on `createCollabPlugin`.

## How It Works

- **`Y.Doc`** stores the document as a `Y.XmlFragment` (ProseMirror node tree)
- **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment
  via `ySyncPlugin`
- **CollaborationCaret extension** renders remote users' cursors with names and
  colors
- **SSE fast-path** — `/_agent-native/poll-events` `EventSource` delivers collab
  events push-style; while SSE is healthy the collab poll interval relaxes to
  ~12 s
- **Polling fallback** — `/_agent-native/poll` is polled every 2 s when SSE
  drops mid-session. On serverless, `/events` answers 204 up front (poll-live)
  and this client relaxes to ~12 s, because `/poll` is the only channel.
- **Collab poll boost** — while the awareness set shows another visible human
  on the doc (agent and hidden tabs do not count), the connection holds
  `acquireCollabPollBoost()` and the shared transport polls every 2.5 s
  whenever no stream is connected: a no-op while SSE or the hosted gateway is
  live. A joiner is noticed on the existing user's next ~12 s collab poll
  (the joiner sees them at once), a leaver within one poll plus the 30 s
  awareness TTL. The boost lapses after 3 minutes with no input and no remote
  events. Lone tabs pay nothing extra. A read-only viewer must join the doc too (Design's
  `useViewerPresence`; it never uses the `ydoc`), or it never sees an editor
  and stays on the idle cadence. A viewer on a different screen than the
  editor shares no doc with them; its own collab poll sees the design's
  resource-scoped events from other tabs and starts the boost (60 s) itself.
- **Update batching** — local Yjs updates are debounced ~80 ms and coalesced
  with `Y.mergeUpdates` before sending; flushed immediately on
  `visibilitychange` / `pagehide`
- **SQL `_collab_docs` table** persists Yjs state as base64 in Postgres. Tombstone
  compaction fires automatically when the stored blob
  exceeds 4× the fresh encoded size.

## Agent + Human Editing

1. **Human edits** → TipTap → ySyncPlugin → Y.XmlFragment → `POST /_agent-native/collab/:docId/update`
2. **Agent edits** → action edits canonical SQL content + bumps `updatedAt` → change-sync refetch → the open editor reconciles the new content into the live Y.Doc (see below) → poll update → all clients

Both produce Yjs operations that merge cleanly. Agent edits appear without
destroying cursor position, selection, or undo history.

The agent does **not** push edits into Yjs in-process and does **not** call any
localhost probe — those approaches silently no-op on serverless (the action runs
in a different process). The peer-editor model below replaced them.

## Agent Edits As A Real-Time Peer Editor

**SQL is the durable source of truth for document body content.** The agent
action edits the canonical content column and bumps `updatedAt`. No localhost
calls, no in-process Yjs mutation.

**The open editor reconciles authoritative external content into the live
Y.Doc.** The `updatedAt` bump flows through change-sync, which refetches the
record. The lead client applies the new content via `setContent`, producing Yjs
operations that merge with concurrent human edits. Every connected client
receives the result through normal Yjs sync.

### The `updatedAt` gate

```ts
// In the editor's reconcile effect
if (loaded.updatedAt > lastAppliedUpdatedAt.current) {
  applyAuthoritativeContent(loaded.content); // adopt
  lastAppliedUpdatedAt.current = loaded.updatedAt;
}
// else: lagging poll / stale snapshot → ignore
```

Without the gate, a slightly-behind poll response re-applies old content and
the edit "reverts on next poll". A fresh mount always adopts whatever content
it loaded.

### Lead-client election

Exactly ONE connected client applies the authoritative snapshot; the rest
receive it through Yjs sync:

```ts
import { isReconcileLeadClient } from "@agent-native/core/client/collab";

if (
  loaded.updatedAt > lastAppliedUpdatedAt.current &&
  isReconcileLeadClient(awareness, ydoc.clientID)
) {
  applyAuthoritativeContent(loaded.content);
}
```

The agent's awareness entry (`AGENT_CLIENT_ID`, max int) can never be the
lead. A sole client is always the lead. The election is deterministic with no
coordination round-trip.

A lead that sees another visible human waits `PEER_SETTLE_MS` (2.5 s) before
adopting a newer snapshot, so that peer's in-flight typing lands first. The wait
is skipped only when the host passes `isEditorClean(liveMarkdown)` to
`useCollabReconcile`, it returns true, and the live doc still equals the last
authoritative snapshot the hook adopted. Do not substitute
`lastAppliedSerialized`: local emits update it, so it cannot say whether the
doc holds unsaved text. Content's `isEditorClean` also requires no queued or
in-flight save, no reconcile recovery draft, and no journaled draft that
differs from the live doc.

### v1 limitation

Full-content reconcile is **last-writer-wins** for the rare case where a human
has unsaved edits in the exact region the agent simultaneously rewrites. Edits
in **different** regions merge fine through the CRDT.

## Security

### Always choose an explicit access mode

Inspect the schema and sharing registration before configuring collaboration:

- For owned or shareable records, use `mode: "resource"` and the resource type
  registered through `registerShareableResource`.
- For records deliberately visibl

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Real Time Collab](https://modelsatlas.com/skills/builderio/real-time-collab/badge.svg)](https://modelsatlas.com/skills/builderio/real-time-collab/)

Not your listing, or something out of date? Claim or update your listing.