Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

fix(docs): doc create --body never reached the database (#278)

Xialie Zhuange47ea5c0bb4b
diff --git a/server/src/__integration__/document-agent-create.test.ts b/server/src/__integration__/document-agent-create.test.ts
new file mode 100644
index 0000000..11017a1
--- /dev/null
+++ b/server/src/__integration__/document-agent-create.test.ts
@@ -0,0 +1,124 @@
+/**
+ * `cumora doc create --body` has to reach the database.
+ *
+ * The CLI runs the whole command in one transaction, inserts the `documents`
+ * row on that client, and then seeds the body through `applyAgentEdit`. The
+ * room's update hook persisted that seed with the GLOBAL pool — a different
+ * connection, which cannot see the still-uncommitted parent row. Postgres does
+ * not wait for it either: there is no row to lock, so the FK check fails
+ * immediately. The failure was swallowed by `console.warn('[docs]
+ * persistUpdate failed')` while the CLI returned ok with `bodyLength` set.
+ *
+ * Nothing looked wrong afterwards. The in-memory room still held the body, and
+ * agent paths never subscribe, so they are never evicted — `doc read` and every
+ * browser on that instance served the body from RAM until the process died.
+ *
+ * And the damage was not limited to the body: the seed is the parent struct for
+ * everything appended later, so subsequent edits persisted as rows that can
+ * never integrate. Measured before the fix: 11 of 20 creates lost the body, and
+ * on a lost one a later `doc append` wrote its row and the cold document still
+ * rendered as "".
+ *
+ * These loop because the underlying defect is a race between the seed's INSERT
+ * and the command's COMMIT. One run reproduces it only about half the time;
+ * ten runs make both directions decisive.
+ */
+import { test, before, beforeEach, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { pool } from '../db/pool.js'
+import { ensureSchemaOnce, resetAllTables, seedCompanyWithAgent, teardownAll } from './_helpers.js'
+import { runCli } from '../agents/cli.js'
+
+const RUNS = 10
+
+before(async () => { await ensureSchemaOnce() })
+beforeEach(async () => { await resetAllTables() })
+after(async () => { await teardownAll() })
+
+/** A live server always has idle pooled connections; a cold pool hides the race
+ * because the seed has to pay a fresh TCP + SCRAM handshake first. */
+async function warmPool(): Promise<void> {
+ await Promise.all([pool.query('SELECT 1'), pool.query('SELECT 1'), pool.query('SELECT 1')])
+}
+
+function documentIdOf(text: string): string {
+ const id = (text.match(/doc_[0-9a-f]+/) ?? [])[0]
+ assert.ok(id, `no document id in CLI output: ${text}`)
+ return id
+}
+
+/** What a restart does: drop the in-memory room and rebuild from the DB. */
+async function coldRead(documentId: string): Promise<string> {
+ const { evictDocumentRoom, readDocumentText } = await import('../documents/rooms.js')
+ evictDocumentRoom(documentId)
+ return String(await readDocumentText(documentId, 'x'))
+}
+
+test('[integration] doc create --body persists the body, every time', async () => {
+ const { agentId } = await seedCompanyWithAgent()
+ await warmPool()
+
+ const missing: string[] = []
+ for (let i = 0; i < RUNS; i++) {
+ const res = await runCli(['--as', agentId, 'doc', 'create', `Doc ${i}`, '--body', `BODY-${i}`])
+ assert.equal(res.ok, true, res.text)
+ const id = documentIdOf(res.text)
+ const { rows } = await pool.query<{ n: number }>(
+ `SELECT count(*)::int AS n FROM document_updates WHERE document_id = $1`, [id],
+ )
+ if (rows[0].n === 0) missing.push(id)
+ }
+
+ assert.deepEqual(
+ missing, [],
+ `${missing.length}/${RUNS} bodies were reported as created and never written to document_updates`,
+ )
+})
+
+test('[integration] the body is still there after a restart', async () => {
+ const { agentId } = await seedCompanyWithAgent()
+ await warmPool()
+
+ for (let i = 0; i < RUNS; i++) {
+ const res = await runCli(['--as', agentId, 'doc', 'create', `Doc ${i}`, '--body', `BODY-${i}`])
+ const id = documentIdOf(res.text)
+ assert.match(
+ await coldRead(id), new RegExp(`BODY-${i}`),
+ `the document is empty on a cold load although the CLI reported it created (run ${i})`,
+ )
+ }
+})
+
+test('[integration] work appended later survives too', async () => {
+ // The severity multiplier: an unpersisted seed makes every later edit an
+ // unintegratable Yjs struct, so a `doc append` that returns ok and writes its
+ // own row still renders as nothing.
+ const { agentId } = await seedCompanyWithAgent()
+ await warmPool()
+
+ for (let i = 0; i < RUNS; i++) {
+ const res = await runCli(['--as', agentId, 'doc', 'create', `Doc ${i}`, '--body', `BODY-${i}`])
+ const id = documentIdOf(res.text)
+ const appended = await runCli(['--as', agentId, 'doc', 'append', id, 'LATER-WORK'])
+ assert.equal(appended.ok, true, appended.text)
+
+ const cold = await coldRead(id)
+ assert.match(cold, /LATER-WORK/, `work appended after the create is gone on a cold load (run ${i})`)
+ assert.match(cold, new RegExp(`BODY-${i}`), `the create body is gone on a cold load (run ${i})`)
+ }
+})
+
+test('[integration] a doc created without --body still works', async () => {
+ // The guard rail: the transactional path must not break the ordinary create,
+ // which produces no seed update at all.
+ const { agentId } = await seedCompanyWithAgent()
+ await warmPool()
+
+ const res = await runCli(['--as', agentId, 'doc', 'create', 'Empty One'])
+ assert.equal(res.ok, true, res.text)
+ const id = documentIdOf(res.text)
+
+ const appended = await runCli(['--as', agentId, 'doc', 'append', id, 'FIRST-CONTENT'])
+ assert.equal(appended.ok, true, appended.text)
+ assert.match(await coldRead(id), /FIRST-CONTENT/)
+})
diff --git a/server/src/documents/rooms.ts b/server/src/documents/rooms.ts
index 2a6883c..ad0cd61 100644
--- a/server/src/documents/rooms.ts
+++ b/server/src/documents/rooms.ts
@@ -70,6 +70,29 @@ const evictions = new Map<string, NodeJS.Timeout>()
* echo-suppressed when they originated here. */
const INSTANCE_ORIGIN = `instance:${env.INSTANCE_ID}`
+/** Persist one update through an explicit client, so it lands inside the
+ * caller's transaction. `doc create --body` seeds the body while its own
+ * `INSERT INTO documents` is still uncommitted; going out on the global pool
+ * means a different connection, where the FK to documents(id) cannot see the
+ * parent row and fails instantly (it does not wait — there is no row to lock).
+ * That failure was swallowed by a console.warn while the CLI reported success,
+ * so the body never reached the database and every later edit became a Yjs
+ * struct whose parent is missing: appended work persisted as a row and still
+ * rendered as nothing on the next cold load. Measured on the project's own
+ * PG 16: 11 of 20 `doc create --body` runs lost the body this way. */
+export async function persistUpdateWith(
+ client: PoolClient,
+ documentId: string,
+ authorId: string,
+ bytes: Uint8Array,
+): Promise<void> {
+ await client.query(
+ `INSERT INTO document_updates (document_id, author_id, update_bytes)
+ VALUES ($1, $2, $3)`,
+ [documentId, authorId, Buffer.from(bytes)],
+ )
+}
+
async function persistUpdate(documentId: string, authorId: string, bytes: Uint8Array): Promise<void> {
await pool.query(
`INSERT INTO document_updates (document_id, author_id, update_bytes)
@@ -161,15 +184,26 @@ async function getOrCreateRoom(
try { s.onUpdate(update, originId) } catch (e) { console.warn('[docs] sub error', e) }
}
+ // A caller editing inside its own transaction takes the update instead:
+ // it writes it on its own client so the row is atomic with whatever else
+ // that transaction is doing (see persistUpdateWith). Fan-out is unchanged.
+ const collectInto = (typeof origin === 'object' && origin !== null && 'collectInto' in origin)
+ ? (origin as { collectInto: Uint8Array[] }).collectInto
+ : null
+
// Persist + fan-out unless this update arrived FROM another instance
// (it's already persisted there + already on the bus).
- if (!isRemote) {
+ if (!isRemote && collectInto) {
+ collectInto.push(update)
+ } else if (!isRemote) {
void persistUpdate(documentId, authorId, update).then(() => {
room.updatesSinceSnapshot += 1
void maybeCompact(room).catch((e) => console.warn('[docs] compact failed', e))
}).catch((e) => {
console.warn('[docs] persistUpdate failed', e)
})
+ }
+ if (!isRemote) {
void publish(CH_DOC_UPDATE, {
type: 'doc.update',
companyId: room.companyId,
@@ -793,7 +827,14 @@ export async function applyAgentEdit(
let imagesDeleted = 0
let blocksReplaced = 0
const deletedStorageKeys: string[] = []
- const origin = { originId: `agent:${agentId}`, authorId: agentId } as never
+ // When the caller is inside a transaction, take the update out of the room's
+ // fire-and-forget persist path and write it on the caller's own client below.
+ // `doc create --body` needs this: its `INSERT INTO documents` is still
+ // uncommitted, so the global pool cannot see the parent row.
+ const collected: Uint8Array[] = []
+ const origin = (dbClient
+ ? { originId: `agent:${agentId}`, authorId: agentId, collectInto: collected }
+ : { originId: `agent:${agentId}`, authorId: agentId }) as never
room.doc.transact(() => {
for (const op of ops) {
if (op.kind === 'append') {
@@ -896,6 +937,17 @@ export async function applyAgentEdit(
}
normalizeMarkdownImageParagraphChildren(fragment)
}, origin)
+ // Awaited, on the caller's client, and NOT swallowed: if this write fails the
+ // command fails, instead of reporting success over a body that never landed.
+ for (const update of collected) {
+ if (!dbClient) break
+ await persistUpdateWith(dbClient, documentId, agentId, update)
+ room.updatesSinceSnapshot += 1
+ }
+ if (collected.length > 0) {
+ void maybeCompact(room).catch((e) => console.warn('[docs] compact failed', e))
+ }
+
return { replaced, imagePlaced, imagesDeleted, blocksReplaced, deletedStorageKeys }
}