diff --git a/src/core/graph/document/activationCoordinator.test.ts b/src/core/graph/document/activationCoordinator.test.ts new file mode 100644 index 00000000000..94c9506be5c --- /dev/null +++ b/src/core/graph/document/activationCoordinator.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, it } from 'vitest' + +import type { DocumentViewBinding } from '@/core/graph/document/activationCoordinator' +import { createActivationCoordinator } from '@/core/graph/document/activationCoordinator' +import type { DocumentId } from '@/types/documentId' +import { toDocumentId } from '@/types/documentId' + +function recordingBinding(log: string[], name: string): DocumentViewBinding { + return { + attach: (id: DocumentId) => log.push(`attach:${name}:${id}`), + detach: (id: DocumentId) => log.push(`detach:${name}:${id}`) + } +} + +function deferred(): { promise: Promise; resolve: () => void } { + let resolve!: () => void + const promise = new Promise((r) => { + resolve = r + }) + return { promise, resolve } +} + +describe('createActivationCoordinator', () => { + it('activates a loaded document and publishes it as active', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => true }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + + const outcome = await coordinator.activate(docA, recordingBinding(log, 'a')) + + expect(outcome).toEqual({ status: 'activated', documentId: docA }) + expect(coordinator.activeDocumentId()).toBe(docA) + expect(log).toEqual([`attach:a:${docA}`]) + }) + + it('rejects activation of a document that is not loaded', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => false }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + + const outcome = await coordinator.activate(docA, recordingBinding(log, 'a')) + + expect(outcome).toEqual({ + status: 'rejected', + documentId: docA, + reason: 'not-loaded' + }) + expect(coordinator.activeDocumentId()).toBeNull() + expect(log).toEqual([]) + }) + + it('rejects when hydration fails and leaves the previous binding intact', async () => { + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => + id === docB ? Promise.reject(new Error('boom')) : Promise.resolve() + }) + const log: string[] = [] + await coordinator.activate(docA, recordingBinding(log, 'a')) + + const outcome = await coordinator.activate(docB, recordingBinding(log, 'b')) + + expect(outcome).toEqual({ + status: 'rejected', + documentId: docB, + reason: 'hydration-failed' + }) + expect(coordinator.activeDocumentId()).toBe(docA) + expect(log).toEqual([`attach:a:${docA}`]) + }) + + it('performs an ordered detach-then-attach handoff between documents', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => true }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + + await coordinator.activate(docA, recordingBinding(log, 'a')) + await coordinator.activate(docB, recordingBinding(log, 'b')) + + expect(log).toEqual([ + `attach:a:${docA}`, + `detach:a:${docA}`, + `attach:b:${docB}` + ]) + expect(coordinator.activeDocumentId()).toBe(docB) + }) + + it('supersedes a slow activate when a newer activate wins the race', async () => { + const slowHydration = deferred() + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => (id === docA ? slowHydration.promise : Promise.resolve()) + }) + const log: string[] = [] + + const first = coordinator.activate(docA, recordingBinding(log, 'a')) + const second = await coordinator.activate(docB, recordingBinding(log, 'b')) + slowHydration.resolve() + const firstOutcome = await first + + expect(second).toEqual({ status: 'activated', documentId: docB }) + expect(firstOutcome).toEqual({ status: 'superseded', documentId: docA }) + expect(coordinator.activeDocumentId()).toBe(docB) + expect(log).toEqual([`attach:b:${docB}`]) + }) + + it('reports superseded when a stale request fails hydration after being overtaken', async () => { + const slowHydration = deferred() + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => + id === docA + ? slowHydration.promise.then(() => { + throw new Error('late failure') + }) + : Promise.resolve() + }) + const log: string[] = [] + + const first = coordinator.activate(docA, recordingBinding(log, 'a')) + await coordinator.activate(docB, recordingBinding(log, 'b')) + slowHydration.resolve() + + expect(await first).toEqual({ status: 'superseded', documentId: docA }) + expect(coordinator.activeDocumentId()).toBe(docB) + }) + + it('deactivate detaches the active document and cancels in-flight activation', async () => { + const slowHydration = deferred() + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => (id === docB ? slowHydration.promise : Promise.resolve()) + }) + const log: string[] = [] + await coordinator.activate(docA, recordingBinding(log, 'a')) + + const inFlight = coordinator.activate(docB, recordingBinding(log, 'b')) + expect(coordinator.deactivate(docA)).toBe(true) + slowHydration.resolve() + + expect(await inFlight).toEqual({ status: 'superseded', documentId: docB }) + expect(coordinator.activeDocumentId()).toBeNull() + expect(log).toEqual([`attach:a:${docA}`, `detach:a:${docA}`]) + }) + + it('deactivate of a non-active document is a no-op', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => true }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + await coordinator.activate(docA, recordingBinding(log, 'a')) + + expect(coordinator.deactivate(docB)).toBe(false) + expect(coordinator.activeDocumentId()).toBe(docA) + }) +}) diff --git a/src/core/graph/document/activationCoordinator.ts b/src/core/graph/document/activationCoordinator.ts new file mode 100644 index 00000000000..da411122aee --- /dev/null +++ b/src/core/graph/document/activationCoordinator.ts @@ -0,0 +1,89 @@ +import type { DocumentId } from '@/types/documentId' + +/** + * View concerns attached by activation and detached by deactivation: the + * renderer/canvas binding, render-attached caches, viewport projection, and + * input/event hooks. Attach and detach must not touch semantic document + * state (ADR-GRAPH-DOCUMENT-0024: activation is presentation). + */ +export interface DocumentViewBinding { + attach(documentId: DocumentId): void + detach(documentId: DocumentId): void +} + +export type ActivationOutcome = + | { status: 'activated'; documentId: DocumentId } + /** A newer activate/deactivate request won the generation race. */ + | { status: 'superseded'; documentId: DocumentId } + | { + status: 'rejected' + documentId: DocumentId + reason: 'not-loaded' | 'hydration-failed' + } + +export interface ActivationCoordinatorDeps { + /** The registry's loaded check for the document being activated. */ + isLoaded(documentId: DocumentId): boolean + /** + * Hydrate and validate the document before the handoff. Runs without + * changing the current binding; a stale request discards this staged work. + */ + hydrate?(documentId: DocumentId): Promise +} + +/** + * Serializes document activation onto the active-canvas binding (ADR-GRAPH-DOCUMENT-0024). + * Requests carry a monotonic generation: a newer request cancels any older + * in-flight one, and a stale request may clean up its private staged work + * but can never detach, attach, or publish. The winning request performs one + * ordered handoff — detach the previous document's view hooks, attach the + * new document's, publish the new active binding — so a late `activate(A)` + * completion cannot overwrite a later `activate(B)`. + */ +export function createActivationCoordinator(deps: ActivationCoordinatorDeps) { + let generation = 0 + let active: { documentId: DocumentId; binding: DocumentViewBinding } | null = + null + + async function activate( + documentId: DocumentId, + binding: DocumentViewBinding + ): Promise { + const requestGeneration = ++generation + const stale = (): boolean => requestGeneration !== generation + try { + await deps.hydrate?.(documentId) + } catch { + return stale() + ? { status: 'superseded', documentId } + : { status: 'rejected', documentId, reason: 'hydration-failed' } + } + if (stale()) return { status: 'superseded', documentId } + if (!deps.isLoaded(documentId)) + return { status: 'rejected', documentId, reason: 'not-loaded' } + + if (active) active.binding.detach(active.documentId) + binding.attach(documentId) + active = { documentId, binding } + return { status: 'activated', documentId } + } + + /** + * Explicit inverse of {@link activate}. Detaches view concerns only; the + * document remains loaded and its domain stores, follower, queue, change + * tracking, and persistence continue to operate. + */ + function deactivate(documentId: DocumentId): boolean { + if (active?.documentId !== documentId) return false + generation++ + active.binding.detach(documentId) + active = null + return true + } + + function activeDocumentId(): DocumentId | null { + return active?.documentId ?? null + } + + return { activate, deactivate, activeDocumentId } +} diff --git a/src/core/graph/document/detachedTargetSession.test.ts b/src/core/graph/document/detachedTargetSession.test.ts new file mode 100644 index 00000000000..4d1a5b13df7 --- /dev/null +++ b/src/core/graph/document/detachedTargetSession.test.ts @@ -0,0 +1,377 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import * as Y from 'yjs' + +import type { + TargetFrame, + TargetFrameApplyPort +} from '@/core/graph/document/detachedTargetSession' +import { createDetachedTargetSession } from '@/core/graph/document/detachedTargetSession' +import { setAssertReporter } from '@/base/assert' + +const WORKFLOW_ID = 'wf-detached' + +/** + * A host document emitting ordered incremental update frames, mirroring the + * doc_update stream a live host produces. + */ +function createFrameSource(workflowId = WORKFLOW_ID) { + const host = new Y.Doc() + let seq = 0 + let lastVector = Y.encodeStateVector(host) + + function frame( + mutate: (doc: Y.Doc) => void, + stamps: Pick = {} + ): TargetFrame { + mutate(host) + const update = Y.encodeStateAsUpdate(host, lastVector) + lastVector = Y.encodeStateVector(host) + seq += 1 + return { workflowId, seq, update, ...stamps } + } + + function diffFrom(stateVector: Uint8Array, atSeq: number): TargetFrame { + return { + workflowId, + seq: atSeq, + update: Y.encodeStateAsUpdate(host, stateVector) + } + } + + return { host, frame, diffFrom } +} + +function setNode(doc: Y.Doc, id: string, fields: Record) { + const nodes = doc.getMap>('nodes') + const node = nodes.get(id) ?? new Y.Map() + if (!nodes.has(id)) nodes.set(id, node) + for (const [key, value] of Object.entries(fields)) node.set(key, value) +} + +function readNodes(update: Uint8Array): Record { + const doc = new Y.Doc() + Y.applyUpdate(doc, update) + const json = doc.getMap('nodes').toJSON() + doc.destroy() + return json +} + +const acceptAll: TargetFrameApplyPort = { apply: () => true } +const rejectAll: TargetFrameApplyPort = { apply: () => false } + +describe('createDetachedTargetSession', () => { + it('commits queued frames in order and reproduces the host state byte-exactly', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'a' }))) + session.enqueue(source.frame((doc) => setNode(doc, '2', { type: 'Sink' }))) + + const drained = session.drainAll(acceptAll) + + expect(drained).toEqual({ committed: 3, stoppedBy: { status: 'idle' } }) + expect(readNodes(session.encodeCommittedState())).toEqual( + source.host.getMap('nodes').toJSON() + ) + const snapshot = session.snapshot() + expect(snapshot.committedSeq).toBe(3) + expect(snapshot.revision).toBe(3) + expect(snapshot.lastCommitId).toBe(`${snapshot.lineage}:3`) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.needsResync).toBe(false) + }) + + it('offers the projection port the frame stamps verbatim and the staged doc with the frame folded in', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + const seen: { frame: TargetFrame; stagedNodes: Record }[] = + [] + const port: TargetFrameApplyPort = { + apply: (frame, stagedDoc) => { + seen.push({ frame, stagedNodes: stagedDoc.getMap('nodes').toJSON() }) + return true + } + } + + const frame = source.frame((doc) => setNode(doc, '1', { type: 'Source' }), { + actor: 'agent:planner', + opIds: ['op-1', 'op-2'] + }) + session.enqueue(frame) + session.commitNext(port) + + expect(seen).toHaveLength(1) + expect(seen[0].frame.actor).toBe('agent:planner') + expect(seen[0].frame.opIds).toEqual(['op-1', 'op-2']) + expect(seen[0].frame.seq).toBe(1) + expect(seen[0].stagedNodes).toEqual({ '1': { type: 'Source' } }) + }) + + it('preserves node incarnation bytes through the staged commit path', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => + setNode(doc, '9', { type: 'Source', __incarnation: 'inc-original-9' }) + ) + ) + + session.commitNext(acceptAll) + + const committed = readNodes(session.encodeCommittedState()) + expect(committed).toEqual({ + '9': { type: 'Source', __incarnation: 'inc-original-9' } + }) + expect(committed).toEqual(source.host.getMap('nodes').toJSON()) + }) + + it('a rejected apply leaves the frame queued and the committed tuple unchanged', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const before = session.snapshot() + const vectorBefore = session.recoveryStateVector() + + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'b' }))) + const failed = session.commitNext(rejectAll) + + expect(failed).toEqual({ status: 'failed', seq: 2 }) + expect(session.snapshot()).toEqual({ ...before, queuedFrames: 1 }) + expect(session.recoveryStateVector()).toEqual(vectorBefore) + + const retried = session.commitNext(acceptAll) + expect(retried).toEqual({ + status: 'committed', + commitId: `${before.lineage}:2`, + seq: 2 + }) + }) + + it('a throwing apply reports failed with the error and keeps the frame queued', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + const boom = new Error('projection exploded') + + const result = session.commitNext({ + apply: () => { + throw boom + } + }) + + expect(result).toEqual({ status: 'failed', seq: 1, error: boom }) + expect(session.snapshot().queuedFrames).toBe(1) + expect(session.snapshot().committedSeq).toBeNull() + }) + + it('skips duplicate frames at or below the last accepted sequence', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + const first = source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + session.enqueue(first) + session.commitNext(acceptAll) + + expect(session.enqueue(first)).toEqual({ status: 'duplicate', seq: 1 }) + + const second = source.frame((doc) => setNode(doc, '1', { title: 'c' })) + session.enqueue(second) + expect(session.enqueue(second)).toEqual({ status: 'duplicate', seq: 2 }) + expect(session.snapshot().queuedFrames).toBe(1) + }) + + it('a sequence gap discards the queue, demands resync, and preserves the recovery state vector', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const recoveryBefore = session.recoveryStateVector() + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'q' }))) + + source.frame((doc) => setNode(doc, '1', { title: 'lost' })) + const gapFrame = source.frame((doc) => setNode(doc, '2', { type: 'Sink' })) + const result = session.enqueue(gapFrame) + + expect(result).toEqual({ status: 'gap', expectedSeq: 3, receivedSeq: 4 }) + const snapshot = session.snapshot() + expect(snapshot.needsResync).toBe(true) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.committedSeq).toBe(1) + expect(session.recoveryStateVector()).toEqual(recoveryBefore) + expect(session.enqueue(gapFrame)).toEqual({ status: 'resync-required' }) + expect(session.commitNext(acceptAll)).toEqual({ + status: 'resync-required' + }) + }) + + it('recovers from a gap by replaying the diff against the last committed state vector', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + + source.frame((doc) => setNode(doc, '1', { title: 'lost' })) + session.enqueue(source.frame((doc) => setNode(doc, '2', { type: 'Sink' }))) + + session.beginResync() + const catchUp = source.diffFrom(session.recoveryStateVector(), 3) + expect(session.enqueue(catchUp)).toEqual({ + status: 'queued', + queuedFrames: 1 + }) + expect(session.commitNext(acceptAll).status).toBe('committed') + expect(readNodes(session.encodeCommittedState())).toEqual( + source.host.getMap('nodes').toJSON() + ) + }) + + it('overflow discards queued frames but keeps the last committed state for recovery', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID, { + maxQueuedFrames: 2 + }) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const recoveryBefore = session.recoveryStateVector() + + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'a' }))) + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'b' }))) + const overflowed = session.enqueue( + source.frame((doc) => setNode(doc, '1', { title: 'c' })) + ) + + expect(overflowed).toEqual({ status: 'overflow', discardedFrames: 2 }) + const snapshot = session.snapshot() + expect(snapshot.needsResync).toBe(true) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.committedSeq).toBe(1) + expect(session.recoveryStateVector()).toEqual(recoveryBefore) + + session.beginResync() + session.enqueue(source.diffFrom(session.recoveryStateVector(), 4)) + session.commitNext(acceptAll) + expect(readNodes(session.encodeCommittedState())).toEqual( + source.host.getMap('nodes').toJSON() + ) + }) + + it('doc_reset starts a fresh document and lineage and invalidates old commit ids', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const oldSnapshot = session.snapshot() + const oldCommitId = oldSnapshot.lastCommitId! + expect(session.isCommitted(oldCommitId)).toBe(true) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { title: 'stale' })) + ) + + session.resetLineage(10) + + const snapshot = session.snapshot() + expect(snapshot.lineage).not.toBe(oldSnapshot.lineage) + expect(snapshot.committedSeq).toBe(10) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.lastCommitId).toBeNull() + expect(session.isCommitted(oldCommitId)).toBe(false) + expect(readNodes(session.encodeCommittedState())).toEqual({}) + + const freshHost = new Y.Doc() + setNode(freshHost, '5', { type: 'Fresh' }) + session.enqueue({ + workflowId: WORKFLOW_ID, + seq: 11, + update: Y.encodeStateAsUpdate(freshHost) + }) + expect(session.commitNext(acceptAll).status).toBe('committed') + expect(session.snapshot().lastCommitId).toBe(`${snapshot.lineage}:11`) + freshHost.destroy() + }) + + describe('cross-target frames', () => { + afterEach(() => { + setAssertReporter(null) + }) + + it('rejects frames addressed to another target loudly in DEV', () => { + vi.stubEnv('DEV', true) + vi.spyOn(console, 'error').mockImplementation(() => {}) + const session = createDetachedTargetSession(WORKFLOW_ID) + const stranger = createFrameSource('wf-other') + + expect(() => + session.enqueue( + stranger.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + ).toThrow(/frames must never cross targets/) + }) + + it('fails closed outside DEV: reported, never queued', () => { + vi.stubEnv('DEV', false) + vi.spyOn(console, 'error').mockImplementation(() => {}) + const reported: string[] = [] + setAssertReporter((message) => reported.push(message)) + const session = createDetachedTargetSession(WORKFLOW_ID) + const stranger = createFrameSource('wf-other') + + const result = session.enqueue( + stranger.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + + expect(result).toEqual({ status: 'rejected', reason: 'cross-target' }) + expect(reported).toHaveLength(1) + expect(reported[0]).toMatch(/frames must never cross targets/) + expect(reported[0]).not.toContain('wf-other') + expect(session.commitNext(acceptAll).status).toBe('idle') + expect(session.snapshot().committedSeq).toBeNull() + }) + }) + + it('isCommitted answers for any sequence at or below the committed head of the same lineage', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'a' }))) + session.drainAll(acceptAll) + const { lineage } = session.snapshot() + + expect(session.isCommitted(`${lineage}:1`)).toBe(true) + expect(session.isCommitted(`${lineage}:2`)).toBe(true) + expect(session.isCommitted(`${lineage}:3`)).toBe(false) + expect(session.isCommitted(`other-lineage:1`)).toBe(false) + expect(session.isCommitted('malformed')).toBe(false) + }) + + it('isCommitted rejects a commit id whose sequence is not a plain nonnegative integer', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.drainAll(acceptAll) + const { lineage } = session.snapshot() + + expect(session.isCommitted(`${lineage}:`)).toBe(false) + expect(session.isCommitted(`${lineage}:-5`)).toBe(false) + expect(session.isCommitted(`${lineage}:1.5`)).toBe(false) + expect(session.isCommitted(`${lineage}: 1`)).toBe(false) + }) +}) diff --git a/src/core/graph/document/detachedTargetSession.ts b/src/core/graph/document/detachedTargetSession.ts new file mode 100644 index 00000000000..356e97ddf0f --- /dev/null +++ b/src/core/graph/document/detachedTargetSession.ts @@ -0,0 +1,265 @@ +import * as Y from 'yjs' + +import { assert } from '@/base/assert' +import { createUuidv4 } from '@/utils/uuid' + +/** + * One ordered effect frame addressed to a target document. Structurally + * compatible with the workbench `DocUpdate` wire frame; declared here so the + * core document seam never imports workbench transport types. + */ +export interface TargetFrame { + readonly workflowId: string + readonly seq: number + readonly update: Uint8Array + readonly actor?: string + /** Accepted semantic op identities folded into this effect frame (DQ-9). */ + readonly opIds?: readonly string[] +} + +/** + * Projects one staged frame into the domain stores. `apply` receives the + * staged document with the frame already folded in; it must be all-or-nothing + * and report whether the projection committed. A `false` return (or a throw) + * leaves the frame queued and the session's committed tuple untouched. + */ +export interface TargetFrameApplyPort { + apply(frame: TargetFrame, stagedDoc: Y.Doc): boolean +} + +export type EnqueueResult = + | { status: 'queued'; queuedFrames: number } + /** `seq` at or below the last accepted frame — replay, skipped. */ + | { status: 'duplicate'; seq: number } + /** Non-contiguous `seq`; queue discarded, resync required. */ + | { status: 'gap'; expectedSeq: number; receivedSeq: number } + /** Queue bound exceeded; queue discarded, resync required. */ + | { status: 'overflow'; discardedFrames: number } + | { status: 'resync-required' } + /** Frame addressed to another target; never queued, in every build. */ + | { status: 'rejected'; reason: 'cross-target' } + +export type CommitResult = + | { status: 'idle' } + | { status: 'resync-required' } + | { status: 'committed'; commitId: string; seq: number } + | { status: 'failed'; seq: number; error?: unknown } + +export interface DetachedTargetSessionSnapshot { + readonly workflowId: string + readonly lineage: string + readonly committedSeq: number | null + readonly revision: number + readonly queuedFrames: number + readonly needsResync: boolean + readonly lastCommitId: string | null +} + +export interface DetachedTargetSessionOptions { + /** Upper bound on staged-but-uncommitted frames. */ + readonly maxQueuedFrames?: number + readonly initialLineage?: string +} + +const DEFAULT_MAX_QUEUED_FRAMES = 64 + +/** + * Staged frame queue for a target document that is not attached to a live + * follower (ADR-GRAPH-DOCUMENT-0024's unloaded-target path). Frames enqueue in wire order + * and commit one at a time: each commit folds the head frame into a clone of + * the last committed Yjs state, offers it to the projection port, and only + * on success publishes the new committed tuple + * `{revision, sequence, stateVector, lineage, lastCommitId}` and dequeues. + * + * The last committed state vector is the recovery anchor: on queue overflow + * or a sequence gap the queued frames are discarded but the committed state + * survives, so the host can be asked for exactly the missing diff + * (`recoveryStateVector`). A `doc_reset` starts a new lineage with a fresh + * document; commit identities (`lineage:seq`) from the old lineage never + * collide with the new one. + */ +export function createDetachedTargetSession( + workflowId: string, + options: DetachedTargetSessionOptions = {} +) { + const maxQueuedFrames = options.maxQueuedFrames ?? DEFAULT_MAX_QUEUED_FRAMES + + let lineage = options.initialLineage ?? createUuidv4() + let committedDoc = new Y.Doc() + let committedSeq: number | null = null + let revision = 0 + let lastCommitId: string | null = null + let needsResync = false + /** `null` accepts any sequence (fresh session or just resynced). */ + let expectedSeq: number | null = null + let queue: TargetFrame[] = [] + + /** + * Loud in DEV (throws), reported in production, and fail-closed in both: + * `assert` returns in non-DEV builds, so callers must still honour `false`. + */ + function isOwnTarget(frameWorkflowId: string): boolean { + const matches = frameWorkflowId === workflowId + assert( + matches, + 'DetachedTargetSession: frame addressed to another target; frames must never cross targets' + ) + return matches + } + + function enqueue(frame: TargetFrame): EnqueueResult { + if (!isOwnTarget(frame.workflowId)) + return { status: 'rejected', reason: 'cross-target' } + if (needsResync) return { status: 'resync-required' } + + const lastAcceptedSeq = queue.at(-1)?.seq ?? committedSeq + if (lastAcceptedSeq !== null && frame.seq <= lastAcceptedSeq) + return { status: 'duplicate', seq: frame.seq } + + if (expectedSeq !== null && frame.seq !== expectedSeq) { + const gapAt = expectedSeq + queue = [] + needsResync = true + return { status: 'gap', expectedSeq: gapAt, receivedSeq: frame.seq } + } + + if (queue.length >= maxQueuedFrames) { + const discardedFrames = queue.length + queue = [] + needsResync = true + return { status: 'overflow', discardedFrames } + } + + queue.push(frame) + expectedSeq = frame.seq + 1 + return { status: 'queued', queuedFrames: queue.length } + } + + function commitNext(port: TargetFrameApplyPort): CommitResult { + if (needsResync) return { status: 'resync-required' } + if (queue.length === 0) return { status: 'idle' } + const frame = queue[0] + + const staged = new Y.Doc() + Y.applyUpdate(staged, Y.encodeStateAsUpdate(committedDoc)) + Y.applyUpdate(staged, frame.update) + + let applied: boolean + try { + applied = port.apply(frame, staged) + } catch (error) { + staged.destroy() + return { status: 'failed', seq: frame.seq, error } + } + if (!applied) { + staged.destroy() + return { status: 'failed', seq: frame.seq } + } + + committedDoc.destroy() + committedDoc = staged + committedSeq = frame.seq + revision += 1 + lastCommitId = `${lineage}:${frame.seq}` + queue.shift() + return { status: 'committed', commitId: lastCommitId, seq: frame.seq } + } + + function drainAll(port: TargetFrameApplyPort): { + committed: number + stoppedBy: CommitResult + } { + let committed = 0 + for (;;) { + const result = commitNext(port) + if (result.status !== 'committed') return { committed, stoppedBy: result } + committed += 1 + } + } + + /** + * State vector of the last committed document state — what the host must + * diff against to replay everything this session is missing. + */ + function recoveryStateVector(): Uint8Array { + return Y.encodeStateVector(committedDoc) + } + + /** Committed Yjs state, byte-exact, for hydration into a live follower. */ + function encodeCommittedState(): Uint8Array { + return Y.encodeStateAsUpdate(committedDoc) + } + + /** + * The host has replayed the missing diff onto the committed state (or will + * send a full catch-up next); accept the next frame at any sequence. + */ + function beginResync(): void { + needsResync = false + queue = [] + expectedSeq = null + } + + /** + * `doc_reset`: the host re-minted the document, so prior updates do not + * compose with what follows. Starts a fresh document and lineage; queued + * frames from the old lineage are meaningless and dropped. + */ + function resetLineage(atSeq: number): void { + committedDoc.destroy() + committedDoc = new Y.Doc() + lineage = createUuidv4() + committedSeq = atSeq + expectedSeq = null + lastCommitId = null + needsResync = false + queue = [] + } + + function isCommitted(commitId: string): boolean { + const separator = commitId.lastIndexOf(':') + if (separator < 0) return false + const commitLineage = commitId.slice(0, separator) + const rawSeq = commitId.slice(separator + 1) + if (!/^\d+$/.test(rawSeq)) return false + const seq = Number(rawSeq) + if (!Number.isSafeInteger(seq)) return false + return ( + commitLineage === lineage && committedSeq !== null && seq <= committedSeq + ) + } + + function snapshot(): DetachedTargetSessionSnapshot { + return { + workflowId, + lineage, + committedSeq, + revision, + queuedFrames: queue.length, + needsResync, + lastCommitId + } + } + + function destroy(): void { + committedDoc.destroy() + queue = [] + } + + return { + enqueue, + commitNext, + drainAll, + recoveryStateVector, + encodeCommittedState, + beginResync, + resetLineage, + isCommitted, + snapshot, + destroy + } +} + +export type DetachedTargetSession = ReturnType< + typeof createDetachedTargetSession +> diff --git a/src/core/graph/document/documentLifecycle.test.ts b/src/core/graph/document/documentLifecycle.test.ts new file mode 100644 index 00000000000..75c79a12ac8 --- /dev/null +++ b/src/core/graph/document/documentLifecycle.test.ts @@ -0,0 +1,139 @@ +import { describe, expect, it } from 'vitest' + +import { + initialDocumentState, + persistenceOf, + reduceDocument +} from './documentLifecycle' +import type { DocumentEvent, DocumentTrackingState } from './documentLifecycle' + +function run( + events: readonly DocumentEvent[], + from: DocumentTrackingState = initialDocumentState +): DocumentTrackingState { + return events.reduce(reduceDocument, from) +} + +describe('reduceDocument', () => { + it('hydrates created to loaded without establishing a persistence baseline', () => { + const loaded = run([{ type: 'hydrated' }]) + expect(loaded.phase).toBe('loaded') + expect(persistenceOf(loaded)).toBe('unsaved') + expect(run([{ type: 'hydrated' }], loaded)).toEqual(loaded) + }) + + it('accumulates mutations while unsaved without changing persistence', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'mutated' } + ]) + expect(state.revision).toBe(2) + expect(persistenceOf(state)).toBe('unsaved') + }) + + it('a completed save makes the document clean only at the captured revision', () => { + const dirty = run([{ type: 'hydrated' }, { type: 'mutated' }]) + const clean = reduceDocument(dirty, { + type: 'saveCompleted', + atRevision: dirty.revision + }) + expect(persistenceOf(clean)).toBe('clean') + }) + + it('a mutation that commits while a save is in flight leaves the document dirty', () => { + const beforeSave = run([{ type: 'hydrated' }, { type: 'mutated' }]) + const capturedRevision = beforeSave.revision + const mutatedDuringSave = reduceDocument(beforeSave, { type: 'mutated' }) + const afterSave = reduceDocument(mutatedDuringSave, { + type: 'saveCompleted', + atRevision: capturedRevision + }) + expect(afterSave.savedRevision).toBe(capturedRevision) + expect(persistenceOf(afterSave)).toBe('dirty') + }) + + it('ignores a save completion ahead of the live revision or behind the baseline', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'saveCompleted', atRevision: 1 } + ]) + expect( + reduceDocument(state, { type: 'saveCompleted', atRevision: 99 }) + ).toEqual(state) + expect( + reduceDocument(state, { type: 'saveCompleted', atRevision: 0 }) + ).toEqual(state) + }) + + it('remote or human mutations after a save make a loaded document dirty again', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'saveCompleted', atRevision: 1 }, + { type: 'mutated' } + ]) + expect(persistenceOf(state)).toBe('dirty') + }) + + it('closes a clean document at its exact revision', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'saveCompleted', atRevision: 1 }, + { type: 'closed', atRevision: 1, discardChanges: false } + ]) + expect(state.phase).toBe('closed') + }) + + it('refuses to close a dirty document without an explicit discard decision', () => { + const dirty = run([{ type: 'hydrated' }, { type: 'mutated' }]) + expect( + reduceDocument(dirty, { + type: 'closed', + atRevision: dirty.revision, + discardChanges: false + }).phase + ).toBe('loaded') + expect( + reduceDocument(dirty, { + type: 'closed', + atRevision: dirty.revision, + discardChanges: true + }).phase + ).toBe('closed') + }) + + it('treats a close decision as stale when the live revision moved past it', () => { + const presented = run([{ type: 'hydrated' }, { type: 'mutated' }]) + const decisionRevision = presented.revision + const moved = reduceDocument(presented, { type: 'mutated' }) + const attempted = reduceDocument(moved, { + type: 'closed', + atRevision: decisionRevision, + discardChanges: true + }) + expect(attempted.phase).toBe('loaded') + }) + + it('ignores mutation and save events after close', () => { + const closed = run([ + { type: 'hydrated' }, + { type: 'closed', atRevision: 0, discardChanges: true } + ]) + expect(reduceDocument(closed, { type: 'mutated' })).toEqual(closed) + expect( + reduceDocument(closed, { type: 'saveCompleted', atRevision: 0 }) + ).toEqual(closed) + }) + + it('cannot close a document that was never loaded', () => { + const attempted = reduceDocument(initialDocumentState, { + type: 'closed', + atRevision: 0, + discardChanges: true + }) + expect(attempted.phase).toBe('created') + }) +}) diff --git a/src/core/graph/document/documentLifecycle.ts b/src/core/graph/document/documentLifecycle.ts new file mode 100644 index 00000000000..7f5f8aae464 --- /dev/null +++ b/src/core/graph/document/documentLifecycle.ts @@ -0,0 +1,74 @@ +/** + * The pure lifecycle/persistence transition of one `GraphDocument` + * (ADR-GRAPH-DOCUMENT-0024). Lifecycle (`created | loaded | closed`) and persistence + * (`unsaved | clean | dirty`) are independent: the first describes document + * existence, the second compares the document with its persistence baseline. + * Persistence is derived from `revision` vs `savedRevision`, never stored. + * + * Save capture happens outside the reducer: a caller captures + * `{ revision, bytes }` before starting I/O and reports `saveCompleted` with + * that exact revision. The baseline advances to the captured revision only, + * so mutations that commit while the save is in flight leave the document + * dirty. Close is a compare-and-set over an exact revision: a decision made + * against a revision that has since moved is stale and ignored. + */ + +type DocumentLifecyclePhase = 'created' | 'loaded' | 'closed' +export type DocumentPersistenceState = 'unsaved' | 'clean' | 'dirty' + +export interface DocumentTrackingState { + readonly phase: DocumentLifecyclePhase + /** Monotonic; incremented by every committed domain mutation. */ + readonly revision: number + /** Persistence baseline revision; `null` until the first completed save. */ + readonly savedRevision: number | null +} + +export type DocumentEvent = + | { type: 'hydrated' } + | { type: 'mutated' } + | { type: 'saveCompleted'; atRevision: number } + | { type: 'closed'; atRevision: number; discardChanges: boolean } + +export const initialDocumentState: DocumentTrackingState = { + phase: 'created', + revision: 0, + savedRevision: null +} + +export function persistenceOf( + state: DocumentTrackingState +): DocumentPersistenceState { + if (state.savedRevision === null) return 'unsaved' + return state.revision === state.savedRevision ? 'clean' : 'dirty' +} + +export function reduceDocument( + state: DocumentTrackingState, + event: DocumentEvent +): DocumentTrackingState { + switch (event.type) { + case 'hydrated': + return state.phase === 'created' ? { ...state, phase: 'loaded' } : state + case 'mutated': + return state.phase === 'closed' + ? state + : { ...state, revision: state.revision + 1 } + case 'saveCompleted': + if (state.phase === 'closed') return state + if (event.atRevision > state.revision) return state + if ( + state.savedRevision !== null && + event.atRevision < state.savedRevision + ) + return state + return { ...state, savedRevision: event.atRevision } + case 'closed': { + if (state.phase !== 'loaded') return state + if (event.atRevision !== state.revision) return state + if (!event.discardChanges && persistenceOf(state) !== 'clean') + return state + return { ...state, phase: 'closed' } + } + } +} diff --git a/src/core/graph/document/documentSerializer.test.ts b/src/core/graph/document/documentSerializer.test.ts new file mode 100644 index 00000000000..8c32b0bf7a3 --- /dev/null +++ b/src/core/graph/document/documentSerializer.test.ts @@ -0,0 +1,68 @@ +import { describe, expect, it, vi } from 'vitest' + +import { createGraphMutations } from '@/workbench/extensions/agent/crdt/graphMutations' +import type { GraphMutations } from '@/workbench/extensions/agent/crdt/graphMutations' +import { inertPlacementPort } from '@/workbench/extensions/agent/crdt/__fixtures__/inertPlacementPort' +import type { RemoteMutationContext } from '@/types/graphMutationContext' +import type { GraphScope } from '@/types/graphScopeId' +import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' +import { toNodeId } from '@/types/nodeId' + +import { serializeDocumentScope } from './documentSerializer' + +const context: RemoteMutationContext = { + source: 'agent-remote', + actor: 'test', + opId: 'op-1' +} + +function scopeFor(graphId: string): GraphScope { + return { + rootGraphId: toRootGraphId(graphId), + owningGraphId: toOwningGraphId(graphId) + } +} + +function mutationsFor(scope: GraphScope): GraphMutations { + return createGraphMutations({ + getScope: () => scope, + layout: { createNode: vi.fn(), deleteNodes: vi.fn() }, + placement: inertPlacementPort + }) +} + +function widgetNames(scope: GraphScope): string[] { + const parsed = JSON.parse( + new TextDecoder().decode(serializeDocumentScope(scope)) + ) as { nodes: { widgets: { name: string }[] }[] } + return parsed.nodes.flatMap(({ widgets }) => widgets.map(({ name }) => name)) +} + +describe('serializeDocumentScope', () => { + it('orders widget names by code unit, not by the ambient collation', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + mutations.addNode({ id: '1', type: 'Source' }, context) + mutations.setWidget(toNodeId('1'), 'apples', 1, context) + mutations.setWidget(toNodeId('1'), 'Bananas', 2, context) + + expect(widgetNames(scope)).toEqual(['Bananas', 'apples']) + }) + + it('serializes a Map-valued widget identically whatever its insertion order', () => { + const forward = scopeFor('forward') + const reverse = scopeFor('reverse') + for (const [scope, entries] of [ + [forward, [['alpha', 1] as const, ['beta', 2] as const]], + [reverse, [['beta', 2] as const, ['alpha', 1] as const]] + ] as const) { + const mutations = mutationsFor(scope) + mutations.addNode({ id: '1', type: 'Source' }, context) + mutations.setWidget(toNodeId('1'), 'opaque', new Map(entries), context) + } + + expect(serializeDocumentScope(forward)).toEqual( + serializeDocumentScope(reverse) + ) + }) +}) diff --git a/src/core/graph/document/documentSerializer.ts b/src/core/graph/document/documentSerializer.ts new file mode 100644 index 00000000000..ed367dddeac --- /dev/null +++ b/src/core/graph/document/documentSerializer.ts @@ -0,0 +1,76 @@ +import { useLinkStore } from '@/stores/linkStore' +import { useNodeDataStore } from '@/stores/nodeDataStore' +import { useWidgetValueStore } from '@/stores/widgetValueStore' +import type { GraphScope } from '@/types/graphScopeId' +import { compareNodeIds } from '@/types/nodeId' + +const RENDER_ONLY_KEYS = new Set(['boundingRect']) + +function compareCodeUnits(left: string, right: string): number { + return left < right ? -1 : left > right ? 1 : 0 +} + +function sortBySerializedForm(entries: readonly unknown[]): unknown[] { + return entries + .map((entry) => [JSON.stringify(entry), entry] as const) + .sort(([left], [right]) => compareCodeUnits(left, right)) + .map(([, entry]) => entry) +} + +function canonicalize(value: unknown): unknown { + if (Array.isArray(value)) return value.map(canonicalize) + // Iteration order of a Map or a Set is insertion order, which differs + // between the full-snapshot rebuild path and the live incremental path. + if (value instanceof Map) + return sortBySerializedForm( + [...value].map(([key, entry]) => [canonicalize(key), canonicalize(entry)]) + ) + if (value instanceof Set) + return sortBySerializedForm([...value].map(canonicalize)) + if (typeof value === 'object' && value !== null) { + const source = value as Record + const result: Record = {} + for (const key of Object.keys(source).sort()) { + if (RENDER_ONLY_KEYS.has(key)) continue + const entry = canonicalize(source[key]) + if (entry !== undefined) result[key] = entry + } + return result + } + return value +} + +/** + * Renderer-independent canonical serialization of one document scope's + * semantic ECS state (ADR-GRAPH-DOCUMENT-0024's persistence seam). Reads only the domain + * stores — never the canvas, layout, or litegraph instances — so the same + * document content produces the same bytes whether the document is active + * on the canvas, activated under a different renderer, or never activated + * at all. Byte equality of two serializations is the save/reload identity + * check. + */ +export function serializeDocumentScope(scope: GraphScope): Uint8Array { + const nodeStore = useNodeDataStore() + const linkStore = useLinkStore() + const widgetStore = useWidgetValueStore() + + const nodes = [ + ...nodeStore.getGraphNodesFor(scope.rootGraphId, scope.owningGraphId) + ] + .sort((left, right) => compareNodeIds(left.id, right.id)) + .map(({ graphId: _graphId, lastSerialization: _cache, ...semantic }) => ({ + ...semantic, + widgets: widgetStore + .getNodeWidgets(scope.rootGraphId, semantic.id) + .map(({ name, type, value }) => ({ name, type, value })) + .sort((left, right) => compareCodeUnits(left.name, right.name)) + })) + + const links = [...linkStore.graphTopologies(scope)] + .sort((left, right) => left.id - right.id) + .map(({ graphId: _graphId, ...topology }) => topology) + + return new TextEncoder().encode( + JSON.stringify(canonicalize({ nodes, links })) + ) +} diff --git a/src/platform/telemetry/TelemetryRegistry.ts b/src/platform/telemetry/TelemetryRegistry.ts index 8d4e7ce1ef5..a19746fda82 100644 --- a/src/platform/telemetry/TelemetryRegistry.ts +++ b/src/platform/telemetry/TelemetryRegistry.ts @@ -6,6 +6,8 @@ import type { AgentNodeTaggedMetadata, AgentPanelClosedMetadata, AgentPanelOpenedMetadata, + AgentReconnectFailedMetadata, + AgentReconnectStartedMetadata, AgentWorkflowAppliedMetadata, AuthErrorMetadata, AuthMetadata, @@ -391,6 +393,14 @@ export class TelemetryRegistry implements TelemetryDispatcher { this.dispatch((provider) => provider.trackAgentWorkflowApplied?.(metadata)) } + trackAgentReconnectFailed(metadata: AgentReconnectFailedMetadata): void { + this.dispatch((provider) => provider.trackAgentReconnectFailed?.(metadata)) + } + + trackAgentReconnectStarted(metadata: AgentReconnectStartedMetadata): void { + this.dispatch((provider) => provider.trackAgentReconnectStarted?.(metadata)) + } + trackWidgetFavoriteToggled(metadata: WidgetFavoriteToggledMetadata): void { this.dispatch((provider) => provider.trackWidgetFavoriteToggled?.(metadata)) } diff --git a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts index 7f8229db460..3764679b531 100644 --- a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts +++ b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts @@ -19,6 +19,8 @@ import type { AgentNodeTaggedMetadata, AgentPanelClosedMetadata, AgentPanelOpenedMetadata, + AgentReconnectFailedMetadata, + AgentReconnectStartedMetadata, AgentWorkflowAppliedMetadata, AuthErrorMetadata, AuthMetadata, @@ -724,6 +726,14 @@ export class PostHogTelemetryProvider implements TelemetryProvider { this.trackEvent(TelemetryEvents.AGENT_WORKFLOW_APPLIED, metadata) } + trackAgentReconnectFailed(metadata: AgentReconnectFailedMetadata): void { + this.trackEvent(TelemetryEvents.AGENT_RECONNECT_FAILED, metadata) + } + + trackAgentReconnectStarted(metadata: AgentReconnectStartedMetadata): void { + this.trackEvent(TelemetryEvents.AGENT_RECONNECT_STARTED, metadata) + } + trackWidgetFavoriteToggled(metadata: WidgetFavoriteToggledMetadata): void { this.trackEvent(TelemetryEvents.WIDGET_FAVORITE_TOGGLED, metadata) } diff --git a/src/platform/telemetry/types.ts b/src/platform/telemetry/types.ts index af84bef3a83..5b7f19795f5 100644 --- a/src/platform/telemetry/types.ts +++ b/src/platform/telemetry/types.ts @@ -600,6 +600,18 @@ export interface AgentWorkflowAppliedMetadata extends Record { workflow_id: string target: 'active_tab_switch' | 'active_tab_open' } +export interface AgentReconnectFailedMetadata extends Record { + attempt: number + error_class: 'subscription_refused' + retryable: boolean + reconnect_duration_ms: number +} +export interface AgentReconnectStartedMetadata extends Record { + disconnect_class: 'socket_reconnect' + attempt: number + last_seen_version: number + offline_duration_ms: number | null +} /** * Widget (input/parameter) favorite toggle tracking metadata. @@ -1296,6 +1308,8 @@ export interface TelemetryProvider { trackAgentNodeTagged?(metadata: AgentNodeTaggedMetadata): void trackAgentAttachButtonClicked?(): void trackAgentWorkflowApplied?(metadata: AgentWorkflowAppliedMetadata): void + trackAgentReconnectFailed?(metadata: AgentReconnectFailedMetadata): void + trackAgentReconnectStarted?(metadata: AgentReconnectStartedMetadata): void // Right side panel widget favorite events trackWidgetFavoriteToggled?(metadata: WidgetFavoriteToggledMetadata): void @@ -1466,6 +1480,8 @@ export const TelemetryEvents = { AGENT_NODE_TAGGED: 'app:agent_node_tagged', AGENT_ATTACH_BUTTON_CLICKED: 'app:agent_attach_button_clicked', AGENT_WORKFLOW_APPLIED: 'app:agent_workflow_applied', + AGENT_RECONNECT_FAILED: 'app:agent_reconnect_failed', + AGENT_RECONNECT_STARTED: 'app:agent_reconnect_started', // Right Side Panel Widget Favorites WIDGET_FAVORITE_TOGGLED: 'app:widget_favorite_toggled', diff --git a/src/stores/graphDocumentStore.test.ts b/src/stores/graphDocumentStore.test.ts new file mode 100644 index 00000000000..5173415ecd4 --- /dev/null +++ b/src/stores/graphDocumentStore.test.ts @@ -0,0 +1,175 @@ +import { describe, expect, it } from 'vitest' + +import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' + +import { useGraphDocumentStore } from './graphDocumentStore' + +const scope = { + rootGraphId: toRootGraphId('root-a'), + owningGraphId: toOwningGraphId('root-a') +} + +describe('useGraphDocumentStore', () => { + it('creates local-only documents that are not agent-addressable', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + expect(documentId).not.toBeNull() + if (documentId === null) return + const entry = store.getDocument(documentId) + expect(entry?.workflowId).toBeNull() + expect(entry?.state.phase).toBe('created') + expect(store.persistenceStateOf(documentId)).toBe('unsaved') + }) + + it('resolves an agent target by workflow id, never by another key', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + expect(documentId).not.toBeNull() + expect(store.resolveWorkflowTarget('wf-1')?.documentId).toBe(documentId) + expect(store.resolveWorkflowTarget('wf-other')).toBeNull() + }) + + it('rejects a duplicate workflow id mapping', () => { + const store = useGraphDocumentStore() + const first = store.createDocument({ workflowId: 'wf-1' }) + expect(first).not.toBeNull() + expect(store.createDocument({ workflowId: 'wf-1' })).toBeNull() + const second = store.createDocument() + if (second === null) throw new Error('createDocument failed') + expect(store.assignWorkflowId(second, 'wf-1')).toBe(false) + }) + + it('rejects a stale reassignment of a document that already has a workflow id', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + if (documentId === null) throw new Error('createDocument failed') + expect(store.assignWorkflowId(documentId, 'wf-2')).toBe(false) + expect(store.assignWorkflowId(documentId, 'wf-1')).toBe(true) + expect(store.getDocument(documentId)?.workflowId).toBe('wf-1') + }) + + it('allows remapping a workflow id after its previous document closed', () => { + const store = useGraphDocumentStore() + const first = store.createDocument({ workflowId: 'wf-1' }) + if (first === null) throw new Error('createDocument failed') + store.hydrateDocument(first, scope) + expect( + store.closeDocument(first, { atRevision: 0, discardChanges: true }) + ).toBe(true) + expect(store.resolveWorkflowTarget('wf-1')).toBeNull() + + const second = store.createDocument() + if (second === null) throw new Error('createDocument failed') + expect(store.assignWorkflowId(second, 'wf-1')).toBe(true) + expect(store.resolveWorkflowTarget('wf-1')?.documentId).toBe(second) + }) + + it('hydration early-binds the scope without requiring a renderer', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + if (documentId === null) throw new Error('createDocument failed') + expect(store.hydrateDocument(documentId, scope)).toBe(true) + const entry = store.getDocument(documentId) + expect(entry?.state.phase).toBe('loaded') + expect(entry?.scope).toEqual(scope) + expect(store.hydrateDocument(documentId, scope)).toBe(false) + }) + + it('rebinds scope only while loaded', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + const rebound = { + rootGraphId: toRootGraphId('root-b'), + owningGraphId: toOwningGraphId('root-b') + } + expect(store.rebindScope(documentId, rebound)).toBe(false) + store.hydrateDocument(documentId, scope) + expect(store.rebindScope(documentId, rebound)).toBe(true) + expect(store.getDocument(documentId)?.scope).toEqual(rebound) + }) + + it('tracks dirtiness across the save capture boundary', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + store.markMutated(documentId) + expect(store.persistenceStateOf(documentId)).toBe('unsaved') + + const ticket = store.beginSave(documentId) + expect(ticket?.revision).toBe(1) + if (!ticket) return + store.markMutated(documentId) + expect(store.completeSave(ticket)).toBe(true) + expect(store.persistenceStateOf(documentId)).toBe('dirty') + + const secondTicket = store.beginSave(documentId) + if (!secondTicket) throw new Error('beginSave failed') + expect(store.completeSave(secondTicket)).toBe(true) + expect(store.persistenceStateOf(documentId)).toBe('clean') + }) + + it('close is compare-and-set: a stale decision must be re-presented', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + store.markMutated(documentId) + const presentedRevision = + store.getDocument(documentId)?.state.revision ?? -1 + store.markMutated(documentId) + expect( + store.closeDocument(documentId, { + atRevision: presentedRevision, + discardChanges: true + }) + ).toBe(false) + expect(store.getDocument(documentId)?.state.phase).toBe('loaded') + expect( + store.closeDocument(documentId, { + atRevision: presentedRevision + 1, + discardChanges: true + }) + ).toBe(true) + }) + + it('refuses to close a dirty document without an explicit discard', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + store.markMutated(documentId) + expect( + store.closeDocument(documentId, { atRevision: 1, discardChanges: false }) + ).toBe(false) + }) + + it('removes only closed documents and clears their stale mapping', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + expect(store.removeDocument(documentId)).toBe(false) + store.closeDocument(documentId, { atRevision: 0, discardChanges: true }) + expect(store.removeDocument(documentId)).toBe(true) + expect(store.getDocument(documentId)).toBeNull() + const next = store.createDocument({ workflowId: 'wf-1' }) + expect(next).not.toBeNull() + }) + + it('isolates state between documents: mutating A never dirties B', () => { + const store = useGraphDocumentStore() + const a = store.createDocument({ workflowId: 'wf-a' }) + const b = store.createDocument({ workflowId: 'wf-b' }) + if (a === null || b === null) throw new Error('createDocument failed') + store.hydrateDocument(a, scope) + store.hydrateDocument(b, { + rootGraphId: toRootGraphId('root-b'), + owningGraphId: toOwningGraphId('root-b') + }) + store.markMutated(a) + expect(store.getDocument(a)?.state.revision).toBe(1) + expect(store.getDocument(b)?.state.revision).toBe(0) + }) +}) diff --git a/src/stores/graphDocumentStore.ts b/src/stores/graphDocumentStore.ts new file mode 100644 index 00000000000..5c48f7541b9 --- /dev/null +++ b/src/stores/graphDocumentStore.ts @@ -0,0 +1,210 @@ +import { defineStore } from 'pinia' +import { shallowReactive } from 'vue' + +import { + initialDocumentState, + persistenceOf, + reduceDocument +} from '@/core/graph/document/documentLifecycle' +import type { + DocumentPersistenceState, + DocumentTrackingState +} from '@/core/graph/document/documentLifecycle' +import type { DocumentId } from '@/types/documentId' +import { createDocumentId } from '@/types/documentId' +import type { GraphScope } from '@/types/graphScopeId' + +export interface GraphDocumentEntry { + readonly documentId: DocumentId + /** Canonical cloud wire address, when assigned. Never used as identity. */ + readonly workflowId: string | null + /** Early-bound ECS scope; set at hydration, independent of any renderer. */ + readonly scope: GraphScope | null + readonly state: DocumentTrackingState +} + +export interface SaveTicket { + readonly documentId: DocumentId + /** The exact revision whose serialized bytes the caller captured. */ + readonly revision: number +} + +/** + * The GraphDocument registry (ADR-GRAPH-DOCUMENT-0024): every workflow document is a + * first-class entry keyed by a stable frontend `document_id`, whether or not + * a tab, renderer, or cloud `workflow_id` exists for it. The registry owns + * the optional `workflow_id → document_id` mapping and rejects duplicate or + * stale mappings; agent frames resolve their target here and never fall back + * to the active canvas. + */ +export const useGraphDocumentStore = defineStore('graphDocument', () => { + const documents = shallowReactive(new Map()) + const documentIdByWorkflowId = shallowReactive(new Map()) + + function getDocument(documentId: DocumentId): GraphDocumentEntry | null { + return documents.get(documentId) ?? null + } + + function resolveWorkflowTarget( + workflowId: string + ): GraphDocumentEntry | null { + const documentId = documentIdByWorkflowId.get(workflowId) + if (documentId === undefined) return null + const entry = documents.get(documentId) + return entry && entry.state.phase !== 'closed' ? entry : null + } + + function persistenceStateOf( + documentId: DocumentId + ): DocumentPersistenceState | null { + const entry = documents.get(documentId) + return entry ? persistenceOf(entry.state) : null + } + + function patch( + documentId: DocumentId, + changes: Partial> + ): GraphDocumentEntry | null { + const entry = documents.get(documentId) + if (!entry) return null + const next = { ...entry, ...changes } + documents.set(documentId, next) + return next + } + + function createDocument(options?: { + workflowId?: string + }): DocumentId | null { + const workflowId = options?.workflowId ?? null + if (workflowId !== null && resolveWorkflowTarget(workflowId) !== null) + return null + const documentId = createDocumentId() + documents.set(documentId, { + documentId, + workflowId, + scope: null, + state: initialDocumentState + }) + if (workflowId !== null) documentIdByWorkflowId.set(workflowId, documentId) + return documentId + } + + /** + * Map a cloud `workflow_id` onto an existing document. Rejects a duplicate + * mapping (the workflow id already addresses another live document) and a + * stale reassignment (the document already carries a different workflow id). + */ + function assignWorkflowId( + documentId: DocumentId, + workflowId: string + ): boolean { + const entry = documents.get(documentId) + if (!entry || entry.state.phase === 'closed') return false + if (entry.workflowId === workflowId) return true + if (entry.workflowId !== null) return false + const incumbent = resolveWorkflowTarget(workflowId) + if (incumbent !== null && incumbent.documentId !== documentId) return false + documentIdByWorkflowId.set(workflowId, documentId) + patch(documentId, { workflowId }) + return true + } + + /** Transition `created → loaded` and early-bind the document's ECS scope. */ + function hydrateDocument(documentId: DocumentId, scope: GraphScope): boolean { + const entry = documents.get(documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { type: 'hydrated' }) + if (state === entry.state || state.phase !== 'loaded') return false + patch(documentId, { state, scope }) + return true + } + + /** Rebind the loaded document's scope, e.g. after its graph id is reminted. */ + function rebindScope(documentId: DocumentId, scope: GraphScope): boolean { + const entry = documents.get(documentId) + if (!entry || entry.state.phase !== 'loaded') return false + patch(documentId, { scope }) + return true + } + + function markMutated(documentId: DocumentId): boolean { + const entry = documents.get(documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { type: 'mutated' }) + if (state === entry.state) return false + patch(documentId, { state }) + return true + } + + /** + * Capture the save point. The caller serializes the document's bytes at + * this exact revision before starting I/O, then reports `completeSave` + * with the ticket. Mutations committed in between leave the document dirty. + */ + function beginSave(documentId: DocumentId): SaveTicket | null { + const entry = documents.get(documentId) + if (!entry || entry.state.phase === 'closed') return null + return { documentId, revision: entry.state.revision } + } + + function completeSave(ticket: SaveTicket): boolean { + const entry = documents.get(ticket.documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { + type: 'saveCompleted', + atRevision: ticket.revision + }) + if (state === entry.state) return false + patch(ticket.documentId, { state }) + return true + } + + /** + * Compare-and-set close over an exact revision. Returns false when the + * decision is stale (the live revision moved) or the document is dirty + * without an explicit discard; the caller must re-present the decision. + */ + function closeDocument( + documentId: DocumentId, + decision: { atRevision: number; discardChanges: boolean } + ): boolean { + const entry = documents.get(documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { + type: 'closed', + atRevision: decision.atRevision, + discardChanges: decision.discardChanges + }) + if (state.phase !== 'closed' || entry.state.phase === 'closed') return false + patch(documentId, { state, scope: null }) + return true + } + + /** Drop a closed document's registry entry and its stale mapping. */ + function removeDocument(documentId: DocumentId): boolean { + const entry = documents.get(documentId) + if (!entry || entry.state.phase !== 'closed') return false + if ( + entry.workflowId !== null && + documentIdByWorkflowId.get(entry.workflowId) === documentId + ) + documentIdByWorkflowId.delete(entry.workflowId) + documents.delete(documentId) + return true + } + + return { + createDocument, + getDocument, + resolveWorkflowTarget, + persistenceStateOf, + assignWorkflowId, + hydrateDocument, + rebindScope, + markMutated, + beginSave, + completeSave, + closeDocument, + removeDocument + } +}) diff --git a/src/types/documentId.ts b/src/types/documentId.ts new file mode 100644 index 00000000000..81360e8b551 --- /dev/null +++ b/src/types/documentId.ts @@ -0,0 +1,18 @@ +import { createUuidv4 } from '@/utils/uuid' + +/** + * Stable frontend-owned identity of a `GraphDocument` (ADR-GRAPH-DOCUMENT-0024). Every + * document has one, including local and unsaved workflows. A cloud-backed + * document may additionally map a canonical `workflow_id` — the wire address + * used by agent commands — but that mapping lives in the document registry; + * it is never the document's own identity. + */ +export type DocumentId = string & { readonly __brand: 'DocumentId' } + +export function toDocumentId(value: string): DocumentId { + return value as DocumentId +} + +export function createDocumentId(): DocumentId { + return createUuidv4() as DocumentId +} diff --git a/src/workbench/extensions/agent/AgentPanelRoot.vue b/src/workbench/extensions/agent/AgentPanelRoot.vue index 6899bb48bf9..c6e057a8250 100644 --- a/src/workbench/extensions/agent/AgentPanelRoot.vue +++ b/src/workbench/extensions/agent/AgentPanelRoot.vue @@ -47,8 +47,10 @@ import type { ComfyWorkflowJSON } from '@/platform/workflow/validation/schemas/w import { blankGraph } from '@/scripts/defaultGraph' import { useAgentNodeSelectionStore } from '@/stores/agentNodeSelectionStore' import { useExecutionErrorStore } from '@/stores/executionErrorStore' +import { useGraphDocumentStore } from '@/stores/graphDocumentStore' import { useWorkflowTabActivityStore } from '@/stores/workflowTabActivityStore' import { useSidebarTabStore } from '@/stores/workspace/sidebarTabStore' +import type { DocumentId } from '@/types/documentId' import { isLGraphNode } from '@/utils/litegraphUtil' import { useToastStore } from '@/platform/updates/common/toastStore' import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' @@ -268,9 +270,13 @@ watch( { immediate: true } ) const { activeTour } = storeToRefs(useOnboardingTourStore()) +const graphDocumentStore = useGraphDocumentStore() const graphMutationsByWorkflow = new Map< string, - ReturnType + { + documentId: DocumentId | null + mutations: ReturnType + } >() const liveWidgets = createLiveWidgetProjection({ getRootGraph: () => app.rootGraphOrUndefined, @@ -278,17 +284,31 @@ const liveWidgets = createLiveWidgetProjection({ markDirty: () => app.canvas?.setDirty(true) }) const graphMutations = (workflowId: string) => { + const documentId = + graphDocumentStore.resolveWorkflowTarget(workflowId)?.documentId ?? + graphDocumentStore.createDocument({ workflowId }) const existing = graphMutationsByWorkflow.get(workflowId) - if (existing) return existing + if (existing && existing.documentId === documentId) return existing.mutations const mutations = createGraphMutations({ + onCommitted() { + if (documentId) graphDocumentStore.markMutated(documentId) + }, getScope() { - const rootGraphId = boundOrOpenWorkflowFor(workflowId)?.activeState?.id - return rootGraphId - ? { - rootGraphId: toRootGraphId(rootGraphId), - owningGraphId: toOwningGraphId(rootGraphId) - } + const registered = documentId + ? (graphDocumentStore.getDocument(documentId)?.scope ?? null) : null + const rootGraphId = boundOrOpenWorkflowFor(workflowId)?.activeState?.id + if (!rootGraphId) return registered + const scope = { + rootGraphId: toRootGraphId(rootGraphId), + owningGraphId: toOwningGraphId(rootGraphId) + } + if (documentId) { + if (!registered) graphDocumentStore.hydrateDocument(documentId, scope) + else if (registered.rootGraphId !== scope.rootGraphId) + graphDocumentStore.rebindScope(documentId, scope) + } + return scope }, layout: { createNode(scope, nodeId, layout, context) { @@ -354,7 +374,7 @@ const graphMutations = (workflowId: string) => { }, liveWidgets }) - graphMutationsByWorkflow.set(workflowId, mutations) + graphMutationsByWorkflow.set(workflowId, { documentId, mutations }) return mutations } diff --git a/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.test.ts b/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.test.ts index b0a317aeae3..2a096d16579 100644 --- a/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.test.ts +++ b/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.test.ts @@ -29,18 +29,21 @@ const GAVE_UP_REPORT = { function wire() { let workflowId: string | null = WORKFLOW_ID const onGaveUp = vi.fn() + const onRefusalExhausted = vi.fn() const resubscribe = vi.fn(() => { if (workflowId !== null) lifecycle.onSubscribeSent(workflowId) }) const lifecycle = new AgentCrdtDocLifecycle( () => workflowId, resubscribe, - onGaveUp + onGaveUp, + onRefusalExhausted ) return { lifecycle, resubscribe, onGaveUp, + onRefusalExhausted, retarget(next: string | null) { workflowId = next } @@ -367,8 +370,8 @@ describe('AgentCrdtDocLifecycle refusal exhaustion', () => { }) }) - it('six consecutive refusals stop retrying with no further subscribe, event, or report', () => { - const { lifecycle, resubscribe, onGaveUp } = wire() + it('reports when six consecutive refusals exhaust the retry budget', () => { + const { lifecycle, resubscribe, onGaveUp, onRefusalExhausted } = wire() lifecycle.onSubscribeSent(WORKFLOW_ID) // Advance to each backoff boundary in two steps so both sides are @@ -417,6 +420,10 @@ describe('AgentCrdtDocLifecycle refusal exhaustion', () => { expect(resubscribe).toHaveBeenCalledTimes(6) expect(lifecycle.shouldDeferSubscribe()).toBe(false) expect(onGaveUp).not.toHaveBeenCalled() + expect(onRefusalExhausted).toHaveBeenCalledExactlyOnceWith({ + attempt: 6, + durationMs: 31_500 + }) expect(reportError).not.toHaveBeenCalled() expect(devEvents().map(({ kind }) => kind)).toEqual([ 'subscribe_retry', diff --git a/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.ts b/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.ts index cf97fd217c8..4c0a4d92c7e 100644 --- a/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.ts +++ b/src/workbench/extensions/agent/crdt/agentCrdtDocLifecycle.ts @@ -167,6 +167,8 @@ export class AgentCrdtDocLifecycle { // no more often than DOC_ID_REFRESH_INTERVAL_MS, so a doc that keeps // delivering frames keeps its rebind window instead of lapsing mid-session. private lastPersistedAt = 0 + private subscribeRetryStartedAt: number | null = null + private subscribeRetryFailureReported = false // PM-1405: caps the fast catch-up probe to one shot per gap episode. Set on // the first confirmed subscribe of an episode, cleared when real content // arrives (the episode is over) or the episode restarts (bind/reconnect). @@ -175,7 +177,11 @@ export class AgentCrdtDocLifecycle { constructor( private readonly workflowId: () => string | null, private readonly resubscribe: () => void, - private readonly onGaveUp: () => void + private readonly onGaveUp: () => void, + private readonly onRefusalExhausted?: (event: { + attempt: number + durationMs: number + }) => void ) {} readPersistedDocId(): string | null { @@ -331,13 +337,31 @@ export class AgentCrdtDocLifecycle { } this.subscribeRetryAttempt = 0 this.ackTimeouts = 0 + this.subscribeRetryStartedAt = null + this.subscribeRetryFailureReported = false } private scheduleSubscribeRetry(): void { if (this.shouldDeferSubscribe()) return - if (this.subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) return + if (this.subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) { + if (!this.subscribeRetryFailureReported) { + this.subscribeRetryFailureReported = true + this.onRefusalExhausted?.({ + attempt: this.subscribeRetryAttempt, + durationMs: Math.max( + 0, + Math.round( + performance.now() - + (this.subscribeRetryStartedAt ?? performance.now()) + ) + ) + }) + } + return + } const target = this.workflowId() if (target === null) return + this.subscribeRetryStartedAt ??= performance.now() const delay = SUBSCRIBE_RETRY_BASE_MS * 2 ** this.subscribeRetryAttempt this.subscribeRetryAttempt += 1 this.subscribeRetryTimer = setTimeout(() => { diff --git a/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts new file mode 100644 index 00000000000..9060fea464c --- /dev/null +++ b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts @@ -0,0 +1,371 @@ +import { + appliedOpIds, + mint, + NODE_INCARNATION_KEY, + nodesMap, + readStamps +} from '@comfyorg/comfy-multi-player' +import type { WidgetCatalog } from '@comfyorg/comfy-multi-player' +import { describe, expect, it, vi } from 'vitest' +import * as Y from 'yjs' + +import { createActivationCoordinator } from '@/core/graph/document/activationCoordinator' +import type { DocumentViewBinding } from '@/core/graph/document/activationCoordinator' +import { createDetachedTargetSession } from '@/core/graph/document/detachedTargetSession' +import type { DetachedTargetSession } from '@/core/graph/document/detachedTargetSession' +import { serializeDocumentScope } from '@/core/graph/document/documentSerializer' +import type { GraphMutations } from './graphMutations' +import { createGraphMutations } from './graphMutations' +import { inertPlacementPort } from './__fixtures__/inertPlacementPort' +import { useGraphDocumentStore } from '@/stores/graphDocumentStore' +import type { DocumentId } from '@/types/documentId' +import type { GraphScope } from '@/types/graphScopeId' +import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' + +import { createTargetFrameApplyPort } from './targetFrameProjection' + +const catalog: WidgetCatalog = { + types: { + Source: { widget_order: ['seed', 'stale'] }, + Sink: { widget_order: [] } + } +} + +const workflowJson = { + nodes: [ + { + id: 1, + type: 'Source', + title: 'Producer', + pos: [10, 20], + size: [180, 90], + inputs: [], + outputs: [{ name: 'out', type: 'IMAGE', links: [9] }], + widgets_values: { seed: 42, stale: 7 } + }, + { + id: 2, + type: 'Sink', + pos: [300, 20], + inputs: [{ name: 'in', type: 'IMAGE', link: 9 }], + outputs: [] + } + ], + links: [[9, 1, 0, 2, 0, 'IMAGE']] as [ + number, + number, + number, + number, + number, + string + ][] +} + +function scopeFor(graphId: string): GraphScope { + return { + rootGraphId: toRootGraphId(graphId), + owningGraphId: toOwningGraphId(graphId) + } +} + +function mutationsFor(scope: GraphScope): GraphMutations { + return createGraphMutations({ + getScope: () => scope, + layout: { createNode: vi.fn(), deleteNodes: vi.fn() }, + placement: inertPlacementPort + }) +} + +function commitHostState( + session: DetachedTargetSession, + workflowId: string, + host: Y.Doc, + mutations: GraphMutations, + seq = 1 +): void { + expect( + session.enqueue({ + workflowId, + seq, + update: Y.encodeStateAsUpdate(host), + actor: 'agent:test', + opIds: [`bootstrap-${seq}`] + }).status + ).toBe('queued') + expect(session.commitNext(createTargetFrameApplyPort(mutations)).status).toBe( + 'committed' + ) +} + +/** A fake renderer-mode binding: activation must never touch semantic state. */ +function modeBinding(log: string[], mode: string): DocumentViewBinding { + return { + attach: () => log.push(`attach:${mode}`), + detach: () => log.push(`detach:${mode}`) + } +} + +function registerLoadedDocument(workflowId: string, scope: GraphScope) { + const registry = useGraphDocumentStore() + const documentId = registry.createDocument({ workflowId }) + if (documentId === null) throw new Error('duplicate workflow mapping') + expect(registry.hydrateDocument(documentId, scope)).toBe(true) + return { registry, documentId } +} + +function loadedCoordinator() { + const registry = useGraphDocumentStore() + return createActivationCoordinator({ + isLoaded: (id: DocumentId) => + registry.getDocument(id)?.state.phase === 'loaded' + }) +} + +describe('document activation persistence (ADR-GRAPH-DOCUMENT-0024 seam)', () => { + it('serializes byte-identically across Base/ECS/Nodes-2.0 activation cycles and save/reload', async () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + + const baseline = serializeDocumentScope(scope) + expect(baseline.length).toBeGreaterThan(2) + + const { registry, documentId } = registerLoadedDocument('wf', scope) + const coordinator = loadedCoordinator() + const log: string[] = [] + + for (const mode of ['base', 'ecs', 'nodes2']) { + const outcome = await coordinator.activate( + documentId, + modeBinding(log, mode) + ) + expect(outcome.status).toBe('activated') + expect(serializeDocumentScope(scope)).toEqual(baseline) + expect(coordinator.deactivate(documentId)).toBe(true) + expect(serializeDocumentScope(scope)).toEqual(baseline) + } + expect(log).toEqual([ + 'attach:base', + 'detach:base', + 'attach:ecs', + 'detach:ecs', + 'attach:nodes2', + 'detach:nodes2' + ]) + + const ticket = registry.beginSave(documentId) + expect(ticket).not.toBeNull() + const savedBytes = serializeDocumentScope(scope) + expect(registry.completeSave(ticket!)).toBe(true) + expect(registry.persistenceStateOf(documentId)).toBe('clean') + + const reloadSession = createDetachedTargetSession('wf') + reloadSession.enqueue({ + workflowId: 'wf', + seq: 1, + update: session.encodeCommittedState() + }) + expect( + reloadSession.commitNext(createTargetFrameApplyPort(mutations)).status + ).toBe('committed') + + expect(serializeDocumentScope(scope)).toEqual(savedBytes) + expect(serializeDocumentScope(scope)).toEqual(baseline) + + session.destroy() + reloadSession.destroy() + host.destroy() + }) + + it('reloads byte-identically while a different renderer mode is active', async () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + const baseline = serializeDocumentScope(scope) + + const otherScope = scopeFor('other-root') + const { documentId: otherDocumentId } = registerLoadedDocument( + 'wf-other', + otherScope + ) + const coordinator = loadedCoordinator() + await coordinator.activate(otherDocumentId, modeBinding([], 'nodes2')) + + const reloadSession = createDetachedTargetSession('wf') + reloadSession.enqueue({ + workflowId: 'wf', + seq: 1, + update: session.encodeCommittedState() + }) + expect( + reloadSession.commitNext(createTargetFrameApplyPort(mutations)).status + ).toBe('committed') + + expect(serializeDocumentScope(scope)).toEqual(baseline) + expect(coordinator.activeDocumentId()).toBe(otherDocumentId) + + session.destroy() + reloadSession.destroy() + host.destroy() + }) + + it('preserves original stamps and DQ-11(c) node incarnations through the staged commit path', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + + const committed = new Y.Doc() + Y.applyUpdate(committed, session.encodeCommittedState()) + + expect(readStamps(committed)).toEqual(readStamps(host)) + expect([...appliedOpIds(committed)].sort()).toEqual( + [...appliedOpIds(host)].sort() + ) + for (const id of ['1', '2']) { + const hostIncarnation = nodesMap(host).get(id)?.get(NODE_INCARNATION_KEY) + expect(typeof hostIncarnation).toBe('string') + expect(nodesMap(committed).get(id)?.get(NODE_INCARNATION_KEY)).toBe( + hostIncarnation + ) + } + + committed.destroy() + session.destroy() + host.destroy() + }) + + it('isolates agent frames from the active canvas: frames land in their registry-resolved scope only', async () => { + const scopeA = scopeFor('root-a') + const scopeB = scopeFor('root-b') + const mutationsA = mutationsFor(scopeA) + const mutationsB = mutationsFor(scopeB) + + const hostA = mint(workflowJson, catalog) + const sessionA = createDetachedTargetSession('wf-a') + commitHostState(sessionA, 'wf-a', hostA, mutationsA) + const bytesA = serializeDocumentScope(scopeA) + + const registryA = registerLoadedDocument('wf-a', scopeA) + const registryB = registerLoadedDocument('wf-b', scopeB) + const registry = useGraphDocumentStore() + + const coordinator = loadedCoordinator() + await coordinator.activate(registryA.documentId, modeBinding([], 'base')) + + const target = registry.resolveWorkflowTarget('wf-b') + expect(target?.documentId).toBe(registryB.documentId) + expect(target?.scope).toEqual(scopeB) + expect(target?.documentId).not.toBe(coordinator.activeDocumentId()) + + const hostB = mint({ nodes: [workflowJson.nodes[1]], links: [] }, catalog) + const sessionB = createDetachedTargetSession('wf-b') + commitHostState(sessionB, 'wf-b', hostB, mutationsB) + + expect(serializeDocumentScope(scopeA)).toEqual(bytesA) + expect(serializeDocumentScope(scopeB)).not.toEqual(bytesA) + + sessionA.destroy() + sessionB.destroy() + hostA.destroy() + hostB.destroy() + }) + + it('recovers a detached target across reconnect via the last committed state vector', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + const baseline = serializeDocumentScope(scope) + + const beforeMissed = Y.encodeStateVector(host) + nodesMap(host).get('1')?.set('title', 'Renamed while offline') + const missedFrame = { + workflowId: 'wf', + seq: 2, + update: Y.encodeStateAsUpdate(host, beforeMissed) + } + nodesMap(host).get('1')?.set('color', '#123456') + + expect(session.enqueue(missedFrame).status).toBe('queued') + const gap = session.enqueue({ + workflowId: 'wf', + seq: 4, + update: Y.encodeStateAsUpdate(host, Y.encodeStateVector(host)) + }) + expect(gap.status).toBe('gap') + expect(serializeDocumentScope(scope)).toEqual(baseline) + + session.beginResync() + session.enqueue({ + workflowId: 'wf', + seq: 4, + update: Y.encodeStateAsUpdate(host, session.recoveryStateVector()) + }) + expect( + session.commitNext(createTargetFrameApplyPort(mutations)).status + ).toBe('committed') + + const committed = new Y.Doc() + Y.applyUpdate(committed, session.encodeCommittedState()) + expect(nodesMap(committed).toJSON()).toEqual(nodesMap(host).toJSON()) + committed.destroy() + + expect(serializeDocumentScope(scope)).not.toEqual(baseline) + + session.destroy() + host.destroy() + }) + + it('doc_reset starts a new lineage whose fresh mint replaces the scope content', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + const oldLineage = session.snapshot().lineage + + session.resetLineage(10) + expect(session.snapshot().lineage).not.toBe(oldLineage) + + const remintedHost = mint( + { nodes: [workflowJson.nodes[0]], links: [] }, + catalog + ) + commitHostState(session, 'wf', remintedHost, mutations, 11) + + const committed = new Y.Doc() + Y.applyUpdate(committed, session.encodeCommittedState()) + expect([...nodesMap(committed).keys()]).toEqual(['1']) + committed.destroy() + + const reloaded = serializeDocumentScope(scope) + const parsed = JSON.parse(new TextDecoder().decode(reloaded)) as { + nodes: { + id: string + inputs?: { link?: number | null }[] + outputs?: { links?: number[] }[] + }[] + links: unknown[] + } + expect(parsed.nodes.map(({ id }) => id)).toEqual(['1']) + expect(parsed.links).toEqual([]) + // The reminted node still declares its pre-reset output link, which the + // replacement lineage no longer contains. + expect( + parsed.nodes.flatMap((node) => + (node.outputs ?? []).map((slot) => slot.links) + ) + ).toEqual([[]]) + + session.destroy() + host.destroy() + remintedHost.destroy() + }) +}) diff --git a/src/workbench/extensions/agent/crdt/graphMutations.test.ts b/src/workbench/extensions/agent/crdt/graphMutations.test.ts index 545e170ec4e..f65eb95f788 100644 --- a/src/workbench/extensions/agent/crdt/graphMutations.test.ts +++ b/src/workbench/extensions/agent/crdt/graphMutations.test.ts @@ -1863,6 +1863,36 @@ describe('graphMutations', () => { expect(widgetContexts).toEqual([context]) }) + it('notifies once after a valid batch commits', () => { + const onCommitted = vi.fn() + const tracked = createGraphMutations({ + getScope: () => scope, + layout: { createNode: createLayout, deleteNodes: deleteLayouts }, + placement, + onCommitted + }) + const error = vi.spyOn(console, 'error').mockImplementation(() => {}) + + expect(tracked.addNode(node(1), context)).toBe(true) + expect(onCommitted).toHaveBeenCalledOnce() + + expect( + tracked.batch(context, (batch) => { + batch.addNode(node(2)) + batch.connect({ + id: 2, + originNodeId: 2, + originSlot: 0, + targetNodeId: 99, + targetSlot: 0, + type: 'IMAGE' + }) + }) + ).toBe(false) + expect(onCommitted).toHaveBeenCalledOnce() + error.mockRestore() + }) + function graphWithStoreOnlyNode() { const graph = new LGraph() createGraphMutations({ diff --git a/src/workbench/extensions/agent/crdt/graphMutations.ts b/src/workbench/extensions/agent/crdt/graphMutations.ts index 49448ffb5e5..37bc1050382 100644 --- a/src/workbench/extensions/agent/crdt/graphMutations.ts +++ b/src/workbench/extensions/agent/crdt/graphMutations.ts @@ -185,6 +185,7 @@ export interface GraphMutationsDeps { layout: SemanticLayoutMutationPort placement: SemanticPlacementPort liveWidgets?: SemanticLiveWidgetMutationPort + onCommitted?: () => void } type QueuedMutation = @@ -1509,6 +1510,7 @@ export function createGraphMutations(deps: GraphMutationsDeps): GraphMutations { if (typeof prepared === 'string') return fail(prepared) offsetInsertedBatch(scope, existingIds, prepared) commit(scope, prepared, context) + deps.onCommitted?.() return true }, addNode(payload, context) { diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts new file mode 100644 index 00000000000..8f58710762c --- /dev/null +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts @@ -0,0 +1,77 @@ +import { linksMap, nodesMap } from '@comfyorg/comfy-multi-player' +import { describe, expect, it } from 'vitest' +import * as Y from 'yjs' + +import type { TargetFrame } from '@/core/graph/document/detachedTargetSession' +import type { GraphMutations, SemanticLinkPayload } from './graphMutations' + +import { createTargetFrameApplyPort } from './targetFrameProjection' + +type GraphMutationBatch = Parameters[1]>[0] + +const frame: TargetFrame = { + workflowId: 'wf', + seq: 1, + update: new Uint8Array() +} + +function recordingMutations(): { + mutations: GraphMutations + links: SemanticLinkPayload[] +} { + const links: SemanticLinkPayload[] = [] + const batch = { + clearSemanticGraph: () => {}, + reconcileNode: () => {}, + connect: (link: SemanticLinkPayload) => { + links.push(link) + } + } as unknown as GraphMutationBatch + const mutations = { + batch: (_context: unknown, define: (batch: GraphMutationBatch) => void) => { + define(batch) + return true + } + } as unknown as GraphMutations + return { mutations, links } +} + +function setNode(doc: Y.Doc, id: string, fields: Record) { + const node = nodesMap(doc).get(id) ?? new Y.Map() + if (!nodesMap(doc).has(id)) nodesMap(doc).set(id, node) + for (const [key, value] of Object.entries(fields)) node.set(key, value) + return node +} + +describe('createTargetFrameApplyPort', () => { + it('orders non-numeric link keys deterministically after the numeric ones', () => { + const doc = new Y.Doc() + setNode(doc, '1', { type: 'Source' }) + setNode(doc, '2', { type: 'Sink' }) + const linkIdByKey = { '10': 10, '2': 2, zz: 700, '1': 1, ab: 800 } + for (const [key, linkId] of Object.entries(linkIdByKey)) + linksMap(doc).set(key, [linkId, '1', 0, '2', 0, 'IMAGE']) + + const { mutations, links } = recordingMutations() + createTargetFrameApplyPort(mutations).apply(frame, doc) + + expect(links.map(({ id }) => id)).toEqual([1, 2, 10, 800, 700]) + doc.destroy() + }) + + it('drops a slot array holding non-record entries instead of forwarding it', () => { + const doc = new Y.Doc() + const source = setNode(doc, '1', { type: 'Source' }) + const outputs = new Y.Array() + outputs.push(['not-a-slot']) + source.set('outputs', outputs) + setNode(doc, '2', { type: 'Sink' }) + linksMap(doc).set('9', [9, '1', 0, '2', 0, 'IMAGE']) + + const { mutations, links } = recordingMutations() + createTargetFrameApplyPort(mutations).apply(frame, doc) + + expect(links[0]?.originOutputs).toEqual([]) + doc.destroy() + }) +}) diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts new file mode 100644 index 00000000000..6578f44af20 --- /dev/null +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts @@ -0,0 +1,203 @@ +import { + linksMap, + nodesMap, + OPAQUE_WIDGETS_KEY +} from '@comfyorg/comfy-multi-player' +import * as Y from 'yjs' + +import type { + TargetFrame, + TargetFrameApplyPort +} from '@/core/graph/document/detachedTargetSession' +import type { + GraphMutations, + SemanticLinkPayload, + SemanticNodePayload +} from './graphMutations' +import type { ISlotType } from '@/lib/litegraph/src/interfaces' +import type { RemoteMutationContext } from '@/types/graphMutationContext' +import { compareNodeIds, toNodeId } from '@/types/nodeId' + +function plain(value: unknown): unknown { + if (value instanceof Y.Map || value instanceof Y.Array) return value.toJSON() + return structuredClone(value) +} + +/** + * Staged-doc counterpart of the adapter's live readers: the adapter reads + * incremental observer effects off its bound follower doc, while this reads + * whole snapshots off a detached session's staged doc. Kept local because the + * projection must never depend on adapter internals (ADR-GRAPH-DOCUMENT-0024's seam). + */ +function readSemanticNode(doc: Y.Doc, id: string): SemanticNodePayload | null { + const source = nodesMap(doc).get(id) + if (!(source instanceof Y.Map)) return null + const type = source.get('type') + if (typeof type !== 'string' || type.length === 0) return null + + const payload: Record = {} + source.forEach((value, key) => { + if (key === 'widgets' && value instanceof Y.Map) { + payload.widgets_values = value.toJSON() + } else if (key === OPAQUE_WIDGETS_KEY) { + payload.widgets_values = plain(value) + } else { + payload[key] = plain(value) + } + }) + return { ...payload, id: toNodeId(id), type } +} + +function isSlotRecord( + value: unknown +): value is Record & { name: string; type: ISlotType } { + if (typeof value !== 'object' || value === null || Array.isArray(value)) + return false + const record = value as Record + return ( + typeof record.name === 'string' && + (typeof record.type === 'string' || typeof record.type === 'number') + ) +} + +function readNodeSlots( + doc: Y.Doc, + id: string, + key: TKey +): SemanticLinkPayload[TKey extends 'inputs' + ? 'targetInputs' + : 'originOutputs'] { + type Slots = SemanticLinkPayload[TKey extends 'inputs' + ? 'targetInputs' + : 'originOutputs'] + const value = nodesMap(doc).get(id)?.get(key) + if (!(value instanceof Y.Array)) return [] as Slots + const slots: unknown = value.toJSON() + if (!Array.isArray(slots) || !slots.every(isSlotRecord)) return [] as Slots + return slots +} + +function readSemanticLink(doc: Y.Doc, id: string): SemanticLinkPayload | null { + const raw = linksMap(doc).get(id) + const tuple = raw instanceof Y.Array ? raw.toArray() : raw + if (!Array.isArray(tuple) || tuple.length < 5) return null + const linkId = Number(tuple[0] ?? id) + const originSlot = Number(tuple[2]) + const targetSlot = Number(tuple[4]) + if ( + !Number.isInteger(linkId) || + tuple[1] == null || + tuple[3] == null || + !Number.isInteger(originSlot) || + !Number.isInteger(targetSlot) + ) { + return null + } + return { + id: linkId, + originNodeId: String(tuple[1]), + originSlot, + targetNodeId: String(tuple[3]), + targetSlot, + type: + typeof tuple[5] === 'string' || typeof tuple[5] === 'number' + ? tuple[5] + : '*', + originOutputs: readNodeSlots(doc, String(tuple[1]), 'outputs'), + targetInputs: readNodeSlots(doc, String(tuple[3]), 'inputs') + } +} + +/** + * Numeric keys ascend numerically; anything else follows them in code-unit + * order. `Number(key)` alone yields `NaN` for a non-numeric key, and a + * comparator returning `NaN` leaves the order implementation-defined. + */ +function compareLinkKeys(left: string, right: string): number { + const integerPattern = /^-?\d+$/ + const leftSeq = integerPattern.test(left) ? Number(left) : null + const rightSeq = integerPattern.test(right) ? Number(right) : null + if (leftSeq !== null && rightSeq !== null) return leftSeq - rightSeq + if (leftSeq !== null) return -1 + if (rightSeq !== null) return 1 + return left < right ? -1 : left > right ? 1 : 0 +} + +function frameContext(frame: TargetFrame): RemoteMutationContext { + const opIds = frame.opIds?.filter((id) => id.length > 0) + return { + source: 'agent-remote', + actor: frame.actor ?? 'agent-replay', + opId: opIds?.at(-1) ?? 'replay', + ...(opIds && opIds.length > 0 && { opIds: [...opIds] }) + } +} + +/** + * A snapshot is authoritative for its own link set, so a slot may not carry a + * reference the snapshot does not contain — that reference would survive into + * the serialized document and outlive the link it names. + */ +function withKnownLinks( + payload: SemanticNodePayload, + knownLinkIds: ReadonlySet +): SemanticNodePayload { + const { inputs, outputs } = payload + return { + ...payload, + ...(Array.isArray(outputs) && { + outputs: outputs.map((slot) => + isSlotRecord(slot) && Array.isArray(slot.links) + ? { + ...slot, + links: slot.links.filter( + (linkId) => + typeof linkId === 'number' && knownLinkIds.has(linkId) + ) + } + : slot + ) + }), + ...(Array.isArray(inputs) && { + inputs: inputs.map((slot) => + isSlotRecord(slot) && + typeof slot.link === 'number' && + !knownLinkIds.has(slot.link) + ? { ...slot, link: null } + : slot + ) + }) + } +} + +/** + * Full-snapshot projection of a detached target session's staged document + * into the ECS stores through the target's `GraphMutations` composite. One + * atomic batch clears the scope and rebuilds it from the staged doc, so a + * validation failure anywhere leaves the stores untouched and the frame + * queued (the session's all-or-nothing commit contract). + */ +export function createTargetFrameApplyPort( + mutations: GraphMutations +): TargetFrameApplyPort { + return { + apply(frame, stagedDoc) { + const nodeIds = [...nodesMap(stagedDoc).keys()].sort((left, right) => + compareNodeIds(toNodeId(left), toNodeId(right)) + ) + const links = [...linksMap(stagedDoc).keys()] + .sort(compareLinkKeys) + .flatMap((id) => readSemanticLink(stagedDoc, id) ?? []) + const knownLinkIds = new Set(links.map(({ id }) => id)) + return mutations.batch(frameContext(frame), (batch) => { + batch.clearSemanticGraph() + for (const id of nodeIds) { + const payload = readSemanticNode(stagedDoc, id) + if (payload) + batch.reconcileNode(withKnownLinks(payload, knownLinkIds)) + } + for (const link of links) batch.connect(link) + }) + } + } +} diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index b6ff69f74cc..04ed1f911ca 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -86,7 +86,9 @@ const definitionsState = vi.hoisted(() => ({ })) const telemetryState = vi.hoisted(() => ({ - reportError: vi.fn() + reportError: vi.fn(), + trackAgentReconnectFailed: vi.fn(), + trackAgentReconnectStarted: vi.fn() })) const apiState = vi.hoisted(() => { @@ -163,6 +165,9 @@ vi.mock(import('./devPanelLog'), () => ({ vi.mock(import('@/platform/telemetry/reportError'), () => ({ reportError: telemetryState.reportError })) +vi.mock(import('@/platform/telemetry'), () => ({ + useTelemetry: () => telemetryState +})) vi.mock(import('@/scripts/api'), () => ({ api: apiState.api })) vi.mock(import('@/scripts/app'), () => ({ @@ -422,6 +427,12 @@ describe('useAgentCrdtFollower', () => { dispatchFrame('doc_subscribed', { ok: false }) vi.advanceTimersByTime(60_000) expect(bridge().resubscribe).toHaveBeenCalledTimes(6) + expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledWith({ + attempt: 6, + error_class: 'subscription_refused', + retryable: true, + reconnect_duration_ms: 31_500 + }) unmount() }) @@ -684,6 +695,42 @@ describe('useAgentCrdtFollower', () => { unmount() }) + it('reports reconnect attempts only after a confirmed subscription', () => { + vi.useFakeTimers({ toFake: ['performance', 'setTimeout', 'clearTimeout'] }) + const { unmount } = mountFollower('wf-1') + + apiState.target.dispatchEvent(new Event('reconnected')) + expect(telemetryState.trackAgentReconnectStarted).not.toHaveBeenCalled() + + dispatchFrame('doc_subscribed', { ok: true }) + vi.advanceTimersByTime(5_000) + apiState.target.dispatchEvent(new Event('reconnected')) + + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenCalledWith({ + disconnect_class: 'socket_reconnect', + attempt: 1, + last_seen_version: 41, + offline_duration_ms: 5_000 + }) + unmount() + }) + + it('uses an accepted reset as the latest reconnect activity', () => { + vi.useFakeTimers({ toFake: ['performance', 'setTimeout', 'clearTimeout'] }) + const { unmount } = mountFollower('wf-1') + dispatchFrame('doc_subscribed', { ok: true }) + vi.advanceTimersByTime(5_000) + dispatchFrame('doc_reset', { workflowId: 'wf-1', seq: 7 }) + vi.advanceTimersByTime(2_000) + + apiState.target.dispatchEvent(new Event('reconnected')) + + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenCalledWith( + expect.objectContaining({ offline_duration_ms: 2_000 }) + ) + unmount() + }) + it('clears only for an explicit reset and rebinds after replacement', () => { const { unmount, status } = mountFollower('wf-1') expect(adapterState.bind).toHaveBeenCalledTimes(1) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index e387146f05d..bbc1ce5a085 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -10,6 +10,7 @@ import { import type { Ref } from 'vue' import * as Y from 'yjs' +import { useTelemetry } from '@/platform/telemetry' import { reportError } from '@/platform/telemetry/reportError' import { api } from '@/scripts/api' import type { RemoteMutationContext } from '@/types/graphMutationContext' @@ -272,6 +273,12 @@ function startAgentCrdtFollower( const updatesApplied = ref(0) const lastFrameType = ref(null) const subscribedWorkflowId = ref(null) + let lastActivityAt: number | null = null + let reconnectAttempt = 0 + let confirmedWorkflowId: string | null = null + const markActivity = (): void => { + lastActivityAt = performance.now() + } const outcomes = ref({ received: 0, applied: 0, @@ -289,6 +296,14 @@ function startAgentCrdtFollower( () => bridge.resubscribe(), () => { connected.value = false + }, + ({ attempt, durationMs }) => { + useTelemetry()?.trackAgentReconnectFailed({ + attempt, + error_class: 'subscription_refused', + retryable: true, + reconnect_duration_ms: durationMs + }) } ) const tabId = createUuidv4() @@ -414,8 +429,12 @@ function startAgentCrdtFollower( recordDevEvent('doc_subscribed', event.detail ?? null) if (ok) { lifecycle.onSubscribeConfirmed() + reconnectAttempt = 0 + confirmedWorkflowId = subscribedWorkflowId.value + markActivity() resumeHeldOpsIfSubscribed() } else { + confirmedWorkflowId = null lifecycle.onSubscribeRefused() // FE #16637 residual: a refusal is the earliest signal the sender can // get that its in-flight batch's doc is gone — don't make it wait out @@ -433,6 +452,7 @@ function startAgentCrdtFollower( return } lifecycle.onDocumentUpdate() + markActivity() updatesApplied.value = bridge.follower.updatesApplied lastFrameType.value = event.type const materialized = applyAndReconcile(update) @@ -467,6 +487,7 @@ function startAgentCrdtFollower( ) return lifecycle.onDocumentResult() + markActivity() lastFrameType.value = event.type recordDevEvent('doc_ops_result', event.detail ?? null) } @@ -481,6 +502,7 @@ function startAgentCrdtFollower( : undefined incrementOutcome('reset') if (!isCurrentWorkflow(detail?.workflowId)) return + markActivity() const context: RemoteMutationContext = { source: 'agent-remote', actor: detail.actor ?? 'agent-reset', @@ -565,6 +587,18 @@ function startAgentCrdtFollower( lifecycle.onSubscribeSent(detail.workflowId) } const onReconnected: EventListener = () => { + if (confirmedWorkflowId !== null) { + reconnectAttempt += 1 + useTelemetry()?.trackAgentReconnectStarted({ + disconnect_class: 'socket_reconnect', + attempt: reconnectAttempt, + last_seen_version: bridge.lastSequence, + offline_duration_ms: + lastActivityAt === null + ? null + : Math.max(0, Math.round(performance.now() - lastActivityAt)) + }) + } connected.value = false lifecycle.onReconnected() recordDevEvent('reconnected', null) @@ -722,6 +756,7 @@ function startAgentCrdtFollower( const justActivated = active && previous?.[1] === false lifecycle.clearForRetarget() connected.value = false + confirmedWorkflowId = null knownDocNodeIds = new Set() pendingLiveNodeIds.clear() if (!active) {