import { linksMap, nodesMap, OPAQUE_WIDGETS_KEY, readStamps, WIDGET_FORM_KEY } from '@comfyorg/comfy-multi-player' import { isEqual, isPlainObject, omit } from 'es-toolkit' import * as Y from 'yjs' import { z } from 'zod' import { applyRemoteDynamicGroupRowCount, dynamicGroupRowAllocationBound, isDynamicGroupController, reachesDynamicGroupRowCount, reportRemoteDynamicGroupRowMismatch } from '@/core/graph/widgets/dynamicGroupDiagnostics' import { growAutogrowInput } from '@/core/graph/widgets/dynamicWidgets' import type { INodeFlags } from '@comfyorg/graph-model/interfaces' import type { INodeInputSlot } from '@comfyorg/graph-model/slots' import { LGraphCanvas } from '@/lib/litegraph/src/LGraphCanvas' import { withGraphIntentSource } from '@/lib/litegraph/src/graphIntents' import { detachSerialisedLinks } from '@/lib/litegraph/src/linkDeduplication' import { LGraphGroup, LGraphNode, LiteGraph } from '@/lib/litegraph/src/litegraph' import type { LGraph } from '@/lib/litegraph/src/litegraph' import { containsCentre } from '@/lib/litegraph/src/measure' import { topologicalSortSubgraphs } from '@/lib/litegraph/src/subgraph/subgraphDeduplication' import type { ExportedSubgraph, ISerialisableNodeInput, ISerialisableNodeOutput, ISerialisedGroup, ISerialisedNode } from '@comfyorg/graph-model/serialisation' import type { IBaseWidget } from '@comfyorg/graph-model/widgets' import { isWidgetValue } from '@comfyorg/graph-model/widgets' import type { ComfyInputsSpec } from '@comfyorg/object-info-parser' import { zDynamicComboOption, zDynamicComboSpecV2 } from '@comfyorg/object-info-parser' import { transformInputSpecV1ToV2 } from '@comfyorg/object-info-parser/migration' import type { InputSpec as InputSpecV2 } from '@comfyorg/object-info-parser/schemas/nodeDefSchemaV2' import { reportError } from '@comfyorg/telemetry/reportError' import { zComfyNode, zGroup } from '@comfyorg/graph-model/workflowSchema' import { BaseWidget } from '@/lib/litegraph/src/widgets/BaseWidget' import { inputSpecTree } from '@/core/graph/nodeDef/inputSpecInterpreter' import { isUuidShapedSubgraphId } from '@/schemas/subgraphIdSchema' import type { LinkId } from '@comfyorg/graph-model/linkId' import { parseLinkId, toLinkId } from '@comfyorg/graph-model/linkId' import type { NodeId } from '@comfyorg/graph-model/nodeId' import { toNodeId } from '@comfyorg/graph-model/nodeId' import type { WidgetValue } from '@/types/simplifiedWidget' import { withLiveAgentTurnWrites } from './agentRemoteProvenance' import { allSubgraphDefinitions, readSubgraphDefinitions, readSubgraphInteriorWidgets } from './agentSubgraphDefinitions' import type { Bounds as PlacementRect, ReadOnlyRect, Rect } from '@comfyorg/shared-frontend-utils/geometry' import { placementOffset } from './batchPlacement' export type NodeChange = 'add' | 'update' | 'delete' /** * What one delivered document frame touched, as collected from Y observers. * Ids are document keys (strings); the applier resolves them against the live * graph. */ type InteriorChanges = ReadonlyMap< string, ReadonlyMap | 'all'> > export interface FrameChanges { nodes: ReadonlyMap /** Widget names edited per node, or `'all'` when the storage was replaced. */ widgets: ReadonlyMap | 'all'> /** Synced node-map keys edited per node. */ resyncNodes: ReadonlyMap> links: ReadonlySet interiors?: InteriorChanges interiorDefinitions?: ReadonlySet /** Root group ids that `meta.groups` gained or lost. */ groups?: ReadonlySet } export interface RemoteApplyContext { actor: string opIds: readonly string[] liveAgentTurn?: boolean } export interface LiveGraphApplierDeps { getGraph(): LGraph | null getCanvas?(): LGraphCanvas | null | undefined /** Scopes layout provenance to the remote actor while `fn` writes. */ withRemoteActor?(actor: string, fn: () => T): T viewportBounds?(): PlacementRect | null /** * True when a local write to the widget register is still in flight and * `docValue` is not it; the frame's value is then left unapplied so the * register is not rewound under the edit. */ holdsLocalWrite?(nodeId: string, widget: string, docValue: unknown): boolean } export interface ApplyResult { createdNodeIds: NodeId[] failureCount: number } /** * `merge` applies one frame's changes on top of the live graph. `replace` * applies the first frame of a new document lineage: the document is the * whole graph, so live nodes and links it does not hold are removed. */ export type ApplyMode = 'merge' | 'replace' /** * Node-map keys mirrored onto a live node when the document edits them. * Structural keys (`inputs`, `outputs`, `pos`, `size`, widget storage) are * excluded: slots follow links, layout stays local. */ export const SYNCED_NODE_FIELDS: ReadonlySet = new Set([ 'title', 'mode', 'flags', 'properties', 'color', 'bgcolor', 'boxcolor', 'shape', 'showAdvanced' ]) const SYNCED_APPEARANCE_FIELDS = [ 'color', 'bgcolor', 'boxcolor', 'shape', 'showAdvanced' ] as const const AGENT_APPLY_TAGS = { subsystem: 'agent-crdt', layer: 'graph-api' } type DocNode = { id: string type: string serialised: ISerialisedNode } & ( | { widgets: Record | unknown[] | undefined widgetRecord?: never } | { widgets?: never; widgetRecord: Record } ) interface DocLink { id: LinkId origin: string originSlot: number target: string targetSlot: number } interface ApplyWidgetOptions { documentWidgets?: DocNode['widgets'] reportMissing?: boolean } function plain(value: unknown): unknown { if (value instanceof Y.Map || value instanceof Y.Array) return value.toJSON() return structuredClone(value) } /** * `flags.ghost` marks a node the user is still placing; the snapshot minted * while placement is live carries it, but the flag is local interaction * state, never document state. */ function syncedFlags(flags: INodeFlags | undefined): INodeFlags { const { ghost: _ghost, ...rest } = flags ?? {} return rest } const zDocSlot = z .object({ name: z.string(), type: z.union([z.string(), z.array(z.string()).nonempty(), z.number()]) }) .passthrough() const zWidgetRecord = z .record(z.string(), z.unknown()) .refine((record) => !Object.hasOwn(record, 'length'), 'has a length key') const zNodeProperty = z.union([ z.string(), z.number(), z.boolean(), z.object({}).passthrough(), z.array(z.unknown()), z.null() ]) /** * The shape a document node must have before it can configure a live node. * Agent-minted nodes are sparse, so geometry and mode fall back to defaults; * slot and property shapes are enforced because `LGraphNode.configure` maps * over them without checking. Slot link references are not validated because * `detachSerialisedLinks` discards them; links come from the links map. * Widget values live in the node's `widgets` map, never in `widgets_values`. */ const zDocNodeFields = zComfyNode .partial({ pos: true, size: true, flags: true, order: true, mode: true }) .omit({ widgets_values: true }) .extend({ id: z.string(), type: z.string().min(1), title: z.string().optional(), inputs: z.array(zDocSlot).optional(), outputs: z.array(zDocSlot).optional(), properties: z.record(z.string(), zNodeProperty.optional()).optional(), [OPAQUE_WIDGETS_KEY]: zWidgetRecord.optional() }) const zDocGroup = zGroup.extend({ id: z.unknown().optional() }) /** * The `meta.groups` records that configure a canvas group, keyed by id; a * record without a usable id is keyed by a hash of its content. */ export function readDocGroups(groups: unknown): Map { const parsed = new Map() if (!Array.isArray(groups)) return parsed for (const record of groups) { const group = zDocGroup.safeParse(structuredClone(record)) if (!group.success) continue const id = isGroupId(group.data.id) ? group.data.id : contentGroupId(group.data) parsed.set(String(id), { ...group.data, id }) } return parsed } function isGroupId(id: unknown): id is number { return typeof id === 'number' && Number.isSafeInteger(id) && id > 0 } function contentGroupId(record: Record): number { const json = canonicalJson(record) let h1 = 0xdeadbeef let h2 = 0x41c6ce57 for (let i = 0; i < json.length; i++) { const code = json.charCodeAt(i) h1 = Math.imul(h1 ^ code, 2654435761) h2 = Math.imul(h2 ^ code, 1597334677) } h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909) h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909) return 4294967296 * (2097151 & h2) + (h1 >>> 0) + 1 } function canonicalJson(value: unknown): string { if (typeof value === 'bigint') return `${value}n` if (value === undefined) return 'null' if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]` if (value !== null && typeof value === 'object') { const entries = Object.entries(value) .filter(([, item]) => item !== undefined) .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)) .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`) return `{${entries.join(',')}}` } return JSON.stringify(value) } /** * Only the actor's kind is reported: the segments after it in * `agent::` and `human::` identify a user. */ type ActorKind = 'agent' | 'human' | 'unknown' type NodeProducer = | { origin: 'operation'; actorKind: ActorKind; opId: string; version: number } | { origin: 'unstamped' | 'unreadable' } interface MalformedDocNode { malformed: string discriminate(): { classType?: string valueShapes: string producer: NodeProducer } } const MAX_SHAPED_ELEMENTS = 16 const MAX_DIAGNOSTIC_CHARS = 1024 const MAX_REPORTED_OP_IDS = 4 const OMISSION_MARKER_CHARS = 8 const MAX_DIAGNOSTIC_LIST_CHARS = 320 interface DiagnosticString { path: readonly (string | number)[] value: string } function elementShape(value: unknown): string { if (value === null) return 'null' if (Array.isArray(value)) return 'array' return typeof value } function valueShape(value: unknown): string { if (value === null) return 'null' if (Array.isArray(value)) { const shaped = value.slice(0, MAX_SHAPED_ELEMENTS).map(elementShape) const omitted = value.length - shaped.length if (omitted > 0) shaped.push(`+${omitted}`) return `array:${value.length}[${shaped.join(',')}]` } if (typeof value === 'object') return `object:${Object.keys(value).length}` return typeof value } function diagnosticWidgetNames(widgets: readonly IBaseWidget[]): string[] { const names: string[] = [] let usedChars = 0 for (const widget of widgets.slice(0, MAX_SHAPED_ELEMENTS)) { if (usedChars + widget.name.length > MAX_DIAGNOSTIC_LIST_CHARS) break names.push(widget.name) usedChars += widget.name.length } const omitted = widgets.length - names.length if (omitted > 0) names.push(`+${omitted}`) return names } function diagnosticStrings( value: unknown, path: readonly (string | number)[] = [] ): DiagnosticString[] { if (typeof value === 'string') return [{ path, value }] if (Array.isArray(value)) { return value.flatMap((entry, index) => diagnosticStrings(entry, [...path, index]) ) } if (!isPlainObject(value)) return [] return Object.entries(value).flatMap(([key, entry]) => diagnosticStrings(entry, [...path, key]) ) } function diagnosticPath(path: readonly (string | number)[]): string { return JSON.stringify(path) } function replaceDiagnosticValue( value: unknown, path: readonly (string | number)[], replacements: ReadonlyMap ): unknown { if (typeof value === 'string') { return replacements.get(diagnosticPath(path)) ?? value } if (Array.isArray(value)) { return value.map((entry, index) => replaceDiagnosticValue(entry, [...path, index], replacements) ) } if (!isPlainObject(value)) return value return Object.fromEntries( Object.entries(value).map(([key, entry]) => [ key, replaceDiagnosticValue(entry, [...path, key], replacements) ]) ) } function replaceDiagnosticStrings( context: Record, replacements: ReadonlyMap ): Record { return Object.fromEntries( Object.entries(context).map(([key, value]) => [ key, replaceDiagnosticValue(value, [key], replacements) ]) ) } function boundedContext( context: Record ): Record { const shortestFirst = diagnosticStrings(context).sort( (left, right) => left.value.length - right.value.length ) let remaining = MAX_DIAGNOSTIC_CHARS const truncated = new Map() for (const { path, value } of shortestFirst) { if (value.length <= remaining) { remaining -= value.length continue } const kept = value.slice(0, Math.max(0, remaining - OMISSION_MARKER_CHARS)) truncated.set( diagnosticPath(path), kept === '' ? '' : `${kept}+${value.length - kept.length}` ) remaining = 0 } if (truncated.size === 0) return context return replaceDiagnosticStrings(context, truncated) } /** `absent` when the path's own key is missing, so it is not read as `undefined`. */ function shapeAtPath(root: unknown, path: readonly PropertyKey[]): string { let cursor: unknown = root for (const [depth, key] of path.entries()) { if (cursor === null || typeof cursor !== 'object') return 'unreachable' if (!Object.hasOwn(cursor, key)) return depth === path.length - 1 ? 'absent' : 'unreachable' cursor = Reflect.get(cursor, key) } return valueShape(cursor) } function issueShapes(fields: unknown, error: z.ZodError): string { return error.issues .map( (issue) => `${issue.path.join('.')} ${issue.code} ${shapeAtPath(fields, issue.path)}` ) .join('; ') } function actorKind(actor: unknown): ActorKind { const kind = typeof actor === 'string' ? actor.split(':', 1)[0] : '' return kind === 'agent' || kind === 'human' ? kind : 'unknown' } function diagnosticActor(actor: string): string { const kind = actorKind(actor) return kind !== 'unknown' && actor.split(':').length === 3 ? kind : actor } function diagnosticApplyContext(context: RemoteApplyContext) { const opIds = context.opIds.slice(0, MAX_REPORTED_OP_IDS) return boundedContext({ actor: diagnosticActor(context.actor), opIds, omittedOpIdCount: context.opIds.length - opIds.length }) } function diagnosticNodeOwner(graph: LGraph, nodeId: NodeId) { const owner = [graph.rootGraph, ...graph.rootGraph.subgraphs.values()].find( (candidate) => candidate.getNodeById(nodeId) !== null ) if (owner === undefined) return { existingOwnerKind: 'unknown' } return { existingOwnerKind: owner === graph.rootGraph ? 'root' : 'subgraph', existingOwnerGraphId: owner.id } } function nodeProducer(doc: Y.Doc, id: string): NodeProducer { let stamps: Readonly> try { stamps = readStamps(doc) } catch { return { origin: 'unreadable' } } const key = JSON.stringify(['node', id]) if (!Object.hasOwn(stamps, key)) return { origin: 'unstamped' } const stamp = stamps[key] if (!Array.isArray(stamp)) return { origin: 'unreadable' } const [version, actor, opId]: unknown[] = stamp if (typeof version !== 'number' || typeof opId !== 'string') return { origin: 'unreadable' } return { origin: 'operation', actorKind: actorKind(actor), opId, version } } function readDocNode( doc: Y.Doc, id: string ): DocNode | MalformedDocNode | null { const source = nodesMap(doc).get(id) if (!(source instanceof Y.Map)) return null const fields: Record = { id } let widgets: DocNode['widgets'] let record: unknown source.forEach((value, key) => { if (key === 'widgets' && value instanceof Y.Map) { widgets = value.toJSON() } else if (key === OPAQUE_WIDGETS_KEY) { const opaque = plain(value) if (Array.isArray(opaque)) widgets = opaque else if (isPlainObject(opaque)) record = opaque } else if (key !== 'id' && key !== WIDGET_FORM_KEY) { fields[key] = plain(value) } }) if (widgets === undefined && record !== undefined) fields[OPAQUE_WIDGETS_KEY] = record const parsed = zDocNodeFields.safeParse(fields) if (!parsed.success) { const { error } = parsed return { malformed: error.issues .map((issue) => `${issue.path.join('.')} ${issue.message}`) .join('; '), discriminate() { return { classType: typeof fields.type === 'string' ? fields.type : undefined, valueShapes: issueShapes(fields, error), producer: nodeProducer(doc, id) } } } } const { pos = [0, 0], size = [0, 0], flags, order = 0, mode = 0, [OPAQUE_WIDGETS_KEY]: widgetRecord, ...rest } = parsed.data const serialised: ISerialisedNode = { ...rest, pos, size, flags: syncedFlags(flags), order, mode } const node = { id, type: serialised.type, serialised } return widgetRecord === undefined ? { ...node, widgets } : { ...node, widgetRecord } } function readDocLink(doc: Y.Doc, key: string): DocLink | null { const raw = linksMap(doc).get(key) const tuple = raw instanceof Y.Array ? raw.toArray() : raw const id = parseLinkId(key) if (id === undefined || id < 0 || !isLinkTuple(tuple, id)) return null return { id, origin: String(tuple[1]), originSlot: Number(tuple[2]), target: String(tuple[3]), targetSlot: Number(tuple[4]) } } /** `[id, origin, originSlot, target, targetSlot, type]` with both endpoints present and integer slots. */ function isLinkTuple(tuple: unknown, id: LinkId): tuple is readonly unknown[] { if (!Array.isArray(tuple) || tuple.length < 5) return false const [tupleId, origin, originSlot, target, targetSlot] = tuple return ( tupleId === id && origin != null && target != null && Number.isInteger(Number(originSlot)) && Number.isInteger(Number(targetSlot)) ) } /** * A document node's slot names in document order (an unnamed slot record is * `undefined` at its position), or null when the document has no such node * or no slot list for it. */ export function readDocSlotNames( doc: Y.Doc, nodeId: string, kind: 'inputs' | 'outputs' ): readonly (string | undefined)[] | null { const slots = nodesMap(doc).get(nodeId)?.get(kind) const list: unknown = slots instanceof Y.Array ? slots.toJSON() : slots if (!Array.isArray(list)) return null return list.map((entry: unknown) => { const name = typeof entry === 'object' && entry !== null && 'name' in entry ? entry.name : undefined return typeof name === 'string' ? name : undefined }) } function readDocSlotName( doc: Y.Doc, nodeId: string, kind: 'inputs' | 'outputs', slot: number ): string | undefined { return readDocSlotNames(doc, nodeId, kind)?.[slot] } /** The document's value for a node's named widget, or undefined when it holds none. */ export function readDocWidgetValue( doc: Y.Doc, nodeId: string, widget: string ): unknown { const widgets = nodesMap(doc).get(nodeId)?.get('widgets') return widgets instanceof Y.Map ? plain(widgets.get(widget)) : undefined } export function docLinksIncident(doc: Y.Doc, nodeId: string): DocLink[] { const links: DocLink[] = [] linksMap(doc).forEach((_, key) => { const link = readDocLink(doc, key) if (link && (link.origin === nodeId || link.target === nodeId)) links.push(link) }) return links } /** * Runs `fn` so that the first link it mints receives `id`. The live graph's * link counter is monotonic; seeding it one below the document id lets * `connect` mint the document's id through its normal path, and the counter * is restored to the higher of the two afterwards so later local mints never * collide with ids the document has already handed out. */ function withLinkId(graph: LGraph, id: LinkId, fn: () => T): T { if (graph.links.has(id)) return fn() const { state } = graph const previous = state.lastLinkId state.lastLinkId = toLinkId(id - 1) try { return fn() } finally { state.lastLinkId = toLinkId(Math.max(previous, state.lastLinkId)) } } function serializableWidgets(node: LGraphNode): IBaseWidget[] { return (node.widgets ?? []).filter((widget) => widget.serialize !== false) } function supportsDynamicWidgetOverflow(node: LGraphNode): boolean { const inputs = node.constructor.nodeData?.inputs return ( inputs !== undefined && Object.values(inputs).some((spec) => inputSpecTree(spec).some(({ type }) => type === 'COMFY_DYNAMICCOMBO_V3') ) ) } const MAX_OPTION_NESTING = 8 const VARIABLE_LENGTH_CONTROL_TYPES = new Set([ 'COMFY_AUTOGROW_V3', 'COMFY_DYNAMICGROUP_V3' ]) interface OptionGate { readonly selector: string readonly optionKey: string } interface OptionOwnedBranch { readonly prefix: string readonly gates: readonly OptionGate[] } interface OptionSelector { readonly name: string readonly widestOptionWidgetCount: number } interface OptionLayout { readonly branches: readonly OptionOwnedBranch[] readonly selectors: readonly OptionSelector[] } const NO_OPTION_LAYOUT: OptionLayout = { branches: [], selectors: [] } const optionLayouts = new WeakMap() function optionLayout(node: LGraphNode): OptionLayout { const { nodeData } = node.constructor if (!nodeData) return NO_OPTION_LAYOUT const cached = optionLayouts.get(nodeData) if (cached) return cached const branches: OptionOwnedBranch[] = [] const selectors: OptionSelector[] = [] for (const [name, spec] of Object.entries(nodeData.inputs)) { const combo = zDynamicComboSpecV2.safeParse(spec) if (!combo.success) continue selectors.push({ name, widestOptionWidgetCount: widestOptionWidgetCount(combo.data, 0) }) collectOptionOwnedBranches(name, combo.data, [], branches, 0) } const layout: OptionLayout = { branches, selectors } optionLayouts.set(nodeData, layout) return layout } function comboOptions(combo: { options: readonly unknown[] }): { key: string; inputs: ComfyInputsSpec }[] { return combo.options.flatMap((candidate) => { const option = zDynamicComboOption.safeParse(candidate) return option.success ? [option.data] : [] }) } function optionChildSpecs(option: { inputs: ComfyInputsSpec }): [string, InputSpecV2][] { const { required, optional } = option.inputs return Object.entries({ ...required, ...optional }).map(([key, child]) => [ key, transformInputSpecV1ToV2(child, { name: key }) ]) } function collectOptionOwnedBranches( selector: string, combo: { options: readonly unknown[] }, gates: readonly OptionGate[], branches: OptionOwnedBranch[], depth: number ): void { if (depth >= MAX_OPTION_NESTING) return for (const option of comboOptions(combo)) { const optionGates = [...gates, { selector, optionKey: option.key }] for (const [key, spec] of optionChildSpecs(option)) { const prefix = `${selector}.${key}` branches.push({ prefix, gates: optionGates }) const nested = zDynamicComboSpecV2.safeParse(spec) if (nested.success) collectOptionOwnedBranches( prefix, nested.data, optionGates, branches, depth + 1 ) } } } function widestOptionWidgetCount( combo: { options: readonly unknown[] }, depth: number ): number { if (depth >= MAX_OPTION_NESTING) return Number.POSITIVE_INFINITY let widest = 0 for (const option of comboOptions(combo)) { let width = 0 for (const [, spec] of optionChildSpecs(option)) { const nested = zDynamicComboSpecV2.safeParse(spec) if (nested.success) width += 1 + widestOptionWidgetCount(nested.data, depth + 1) else if (VARIABLE_LENGTH_CONTROL_TYPES.has(spec.type)) return Number.POSITIVE_INFINITY else width += 1 } widest = Math.max(widest, width) } return widest } const OVERFLOW_WIDGET_NAME_RE = /^_extra_(0|[1-9]\d*)$/ function overflowWidgetIndex(name: string): number | null { const match = OVERFLOW_WIDGET_NAME_RE.exec(name) return match ? Number(match[1]) : null } type OptionOwnership = 'selectedOption' | 'unselectedOption' | 'noOption' const OWNERSHIP_PRECEDENCE: Record = { noOption: 0, unselectedOption: 1, selectedOption: 2 } function liveSelectedOptionKey( node: LGraphNode, selector: string ): string | undefined { const value = node.widgets?.find(({ name }) => name === selector)?.value return typeof value === 'string' ? value : undefined } function branchOwnership( node: LGraphNode, branch: OptionOwnedBranch ): OptionOwnership { for (const { selector, optionKey } of branch.gates) { const selected = liveSelectedOptionKey(node, selector) if (selected === undefined) return 'noOption' if (selected !== optionKey) return 'unselectedOption' } return 'selectedOption' } function optionOwnership(node: LGraphNode, name: string): OptionOwnership { let longestPrefix = -1 let ownership: OptionOwnership = 'noOption' for (const branch of optionLayout(node).branches) { if (name !== branch.prefix && !name.startsWith(`${branch.prefix}.`)) continue const { length } = branch.prefix if (length < longestPrefix) continue const verdict = branchOwnership(node, branch) if (length > longestPrefix) { longestPrefix = length ownership = verdict } else if (OWNERSHIP_PRECEDENCE[verdict] > OWNERSHIP_PRECEDENCE[ownership]) ownership = verdict } return ownership } function widestSelectionWidgetCount(node: LGraphNode): number { const widgets = serializableWidgets(node) return optionLayout(node).selectors.reduce( (total, { name, widestOptionWidgetCount: widest }) => total + Math.max( 0, widest - widgets.filter(({ name: widget }) => widget.startsWith(`${name}.`)) .length ), widgets.length ) } function selectionDependentAbsence(node: LGraphNode, name: string): boolean { const index = overflowWidgetIndex(name) return index === null ? optionOwnership(node, name) === 'unselectedOption' : index < widestSelectionWidgetCount(node) } function documentWidget( node: LGraphNode, name: string ): IBaseWidget | undefined { return ( node.widgets?.find((widget) => widget.name === name) ?? overflowWidget(node, name) ) } /** The live widget an overflow alias addresses, if the node has that position. */ function overflowWidget( node: LGraphNode, name: string ): IBaseWidget | undefined { const overflowIndex = overflowWidgetIndex(name) return overflowIndex === null ? undefined : serializableWidgets(node).at(overflowIndex) } /** * Whether `name` is an overflow alias for a position the document also * addresses by the live widget's real name; the named entry wins. Judged * against the node's whole document map so an alias-only partial frame cannot * overwrite the named value. */ function supersededOverflowAlias( node: LGraphNode, name: string, document: DocNode['widgets'] ): boolean { if (document === undefined || Array.isArray(document)) return false if (node.widgets?.some((widget) => widget.name === name)) return false const positional = overflowWidget(node, name) return positional !== undefined && Object.hasOwn(document, positional.name) } function closestController( node: LGraphNode, name: string ): IBaseWidget | undefined { let controller: IBaseWidget | undefined for (const widget of node.widgets ?? []) { if (!isDynamicGroupController(widget)) continue if (!name.startsWith(`${widget.name}.`)) continue if (!controller || widget.name.length > controller.name.length) controller = widget } return controller } function hiddenRowController( node: LGraphNode, name: string ): IBaseWidget | undefined { const controller = closestController(node, name) if (!controller) return undefined const [index, ...field] = name.slice(controller.name.length + 1).split('.') if (!/^(0|[1-9]\d*)$/.test(index) || !field.length || !field.every(Boolean)) return undefined const count = controller.value return typeof count === 'number' && Number(index) >= count ? controller : undefined } function regrownRow( node: LGraphNode, name: string, names: ReadonlySet ): boolean { const controller = hiddenRowController(node, name) return controller !== undefined && names.has(controller.name) } function deferredRowCounts( node: LGraphNode, constructed: readonly IBaseWidget[], widgets: DocNode['widgets'] ): ReadonlySet { if ( widgets === undefined || Array.isArray(widgets) || supportsDynamicWidgetOverflow(node) ) return new Set() return new Set( constructed .filter( (widget) => isDynamicGroupController(widget) && Object.hasOwn(widgets, widget.name) ) .map((widget) => widget.name) ) } /** * Document entries for widgets that only exist after `configure`: aliases past * the constructed list, and names the constructor did not build but the node * now serializes. `constructed` is the serializable list from before * `configure`; a name that still matches nothing is dropped without a report. */ function mountedWidgetValues( node: LGraphNode, widgets: DocNode['widgets'], constructed: readonly IBaseWidget[], constructedNames: ReadonlySet, deferred: ReadonlySet ): Record | undefined { if (widgets === undefined || Array.isArray(widgets)) return undefined const mounted = Object.entries(widgets).filter(([name]) => { const index = overflowWidgetIndex(name) return index === null ? !constructedNames.has(name) || deferred.has(name) : overflowWidget(node, name) === undefined || index >= constructed.length }) return mounted.length === 0 ? undefined : Object.fromEntries(mounted) } /** * The document stores an ordinary node's widget values by name; `configure` * restores them positionally over the node's serializable widgets, so project * the named map into that order, keeping the constructor default for any * widget the document does not mention. */ function positionalWidgetValues( node: LGraphNode, widgets: DocNode['widgets'], deferred: ReadonlySet ): WidgetValue[] | undefined { if (widgets === undefined) return undefined if (Array.isArray(widgets)) { return widgets.map((value): WidgetValue => isWidgetValue(value) ? value : undefined ) } return serializableWidgets(node).map((widget, index) => { if (deferred.has(widget.name)) return widget.value const alias = `_extra_${index}` const name = Object.hasOwn(widgets, widget.name) ? widget.name : overflowWidget(node, alias) === widget && Object.hasOwn(widgets, alias) ? alias : widget.name const value = widgets[name] return Object.hasOwn(widgets, name) && isWidgetValue(value) ? value : widget.value }) } function addGroup(graph: LGraph, serialised: ISerialisedGroup): LGraphGroup { const group = new LGraphGroup() group.configure(serialised) graph.add(group) return group } function missingNode(docNode: DocNode): LGraphNode { const node = new LGraphNode( docNode.serialised.title || docNode.type || 'Missing Node', docNode.type ) node.has_errors = true return node } /** * A document may carry a size smaller than the node's widgets need (or none * at all). Every human path — `loadGraphData`, which the undo stack restores * through, and interactive resize — floors the size at `computeSize()`, so a * node born below that floor snapshots at one size and restores at another, * which the change tracker then records as a fresh edit. */ function floorSizeToContent(node: LGraphNode): void { const [minWidth, minHeight] = node.computeSize() const [width, height] = node.size if (width >= minWidth && height >= minHeight) return node.setSize([Math.max(width, minWidth), Math.max(height, minHeight)]) } function configureRemoteNode(node: LGraphNode, info: ISerialisedNode): void { applyRemoteDynamicGroupRowCount(node, () => node.configure(info)) } function widgetAcceptedValue(widget: IBaseWidget, value: WidgetValue): boolean { return ( !isDynamicGroupController(widget) || reachesDynamicGroupRowCount(widget, value) ) } export class LiveGraphApplier { private readonly deps: LiveGraphApplierDeps private readonly reported = new Set() private readonly interiorIds = new Map>() private readonly failureCounts: number[] = [] private readonly unappliedRegrownRows = new WeakMap< LGraphNode, ReadonlySet >() constructor(deps: LiveGraphApplierDeps) { this.deps = deps } /** Applies the collected changes of one delivered frame to the live graph. */ applyChanges( doc: Y.Doc, changes: FrameChanges, context: RemoteApplyContext, mode: ApplyMode = 'merge' ): ApplyResult { const graph = this.deps.getGraph() if (!graph) return { createdNodeIds: [], failureCount: 0 } this.failureCounts.push(0) try { return this.write(graph, context, () => { if (mode === 'replace') this.removeAbsent(graph, doc, context) const created: NodeId[] = [] const touchedNodes = new Set() this.registerDefinitions(graph, doc) for (const [id, change] of changes.nodes) { if (change === 'delete') { this.try(context, () => this.deleteNode(graph, id)) continue } touchedNodes.add(id) this.try(context, () => { const result = this.upsertNode(graph, doc, id, mode, context) if (result === 'created') created.push(toNodeId(id)) if (result === 'created' || result === 'recreated') { for (const link of docLinksIncident(doc, id)) { this.connectLink(graph, doc, link) } } }) } for (const [id, keys] of changes.resyncNodes) { if (touchedNodes.has(id)) continue this.try(context, () => this.syncFields(graph, doc, id, keys)) } for (const [id, names] of changes.widgets) { if (touchedNodes.has(id)) continue this.try(context, () => this.syncWidgets(graph, doc, id, names, mode)) } this.applyInteriors(graph, doc, changes, context, mode) this.applyLinks(graph, doc, [...changes.links], context) const createdGroups = this.applyGroups( graph, doc, changes.groups, context ) if (mode === 'merge') this.placeBatch(graph, created, createdGroups, { moveCollisions: context.liveAgentTurn === true }) return { createdNodeIds: created, failureCount: this.currentFailureCount() } }) } finally { this.failureCounts.pop() } } private removeAbsent( graph: LGraph, doc: Y.Doc, context: RemoteApplyContext ): void { const docNodes = nodesMap(doc) const absentNodes = graph._nodes.filter( (node) => !docNodes.has(String(node.id)) ) for (const node of absentNodes) { this.try(context, () => graph.remove(node)) } const docLinks = linksMap(doc) for (const id of graph.links.keys()) { if (docLinks.has(String(id))) continue this.try(context, () => graph.removeLink(id)) } const docGroups = readDocGroups(doc.getMap('meta').get('groups')) const absentGroups = graph.groups.filter( (group) => !docGroups.has(String(group.id)) ) for (const group of absentGroups) { this.try(context, () => graph.remove(group)) } } private write(graph: LGraph, context: RemoteApplyContext, fn: () => T): T { const withActor = this.deps.withRemoteActor ?? ((_, run) => run()) return withActor(context.actor, () => { const canvas = this.deps.getCanvas?.() canvas?.emitBeforeChange() try { return withLiveAgentTurnWrites( { isLiveAgentTurn: context.liveAgentTurn === true }, () => withGraphIntentSource('agent-remote', fn) ) } finally { if (canvas) canvas.setDirty(true, true) else graph.setDirtyCanvas(true, true) canvas?.emitAfterChange() } }) } private try(context: RemoteApplyContext, fn: () => void): void { try { fn() } catch (error) { this.incrementFailureCount() reportError(error, { surface: 'agent', errorType: 'agent_graph_apply_failed', tags: { ...AGENT_APPLY_TAGS, outcome: 'degraded' }, context: diagnosticApplyContext(context) }) } } private reportOnce( key: string, message: string, errorType: string, context: Record, cause?: unknown ): void { this.incrementFailureCount() if (this.reported.has(key)) return this.reported.add(key) reportError( cause === undefined ? new Error(message) : new Error(message, { cause }), { surface: 'agent', errorType, tags: { ...AGENT_APPLY_TAGS, outcome: 'degraded' }, context: boundedContext(context) } ) } private currentFailureCount(): number { return this.failureCounts.at(-1) ?? 0 } private incrementFailureCount(): void { const index = this.failureCounts.length - 1 if (index >= 0) this.failureCounts[index] += 1 } private registerDefinitions(graph: LGraph, doc: Y.Doc): void { const rootGraph = graph.rootGraph const missing = allSubgraphDefinitions(readSubgraphDefinitions(doc)) .map((definition) => ({ ...definition, definitions: undefined })) .filter((definition) => !rootGraph.subgraphs.has(definition.id)) if (missing.length === 0) return const reserved = docRootIds(doc) for (const definition of topologicalSortSubgraphs(missing)) { const failure = tryCreateSubgraph(rootGraph, definition, reserved) if (failure === undefined) { this.reported.delete(`definition:${definition.id}`) this.recordInteriorIds(rootGraph, definition) continue } this.incrementFailureCount() if (this.reported.has(`definition:${definition.id}`)) continue this.reported.add(`definition:${definition.id}`) reportError(failure, { surface: 'agent', errorType: 'agent_subgraph_definitions_failed', tags: { ...AGENT_APPLY_TAGS, outcome: 'degraded' }, context: { graphId: graph.id, definitionId: definition.id } }) } } private recordInteriorIds( rootGraph: LGraph, definition: ExportedSubgraph ): void { const live = rootGraph.subgraphs.get(definition.id) if (!live || !definition.nodes) return this.recordInteriorMapping( definition.id, definition.nodes.map((node) => String(node.id)), live.nodes ) } private recordInteriorMapping( definitionId: string, orderedDocIds: readonly string[], liveNodes: readonly LGraphNode[] ): void { if (orderedDocIds.length !== liveNodes.length) return const mapping = new Map() for (const [index, docId] of orderedDocIds.entries()) { mapping.set(docId, liveNodes[index].id) } this.interiorIds.set(definitionId, mapping) } private deleteNode(graph: LGraph, id: string): void { const node = graph.getNodeById(toNodeId(id)) if (node) graph.remove(node) } private applyGroups( graph: LGraph, doc: Y.Doc, ids: ReadonlySet | undefined, context: RemoteApplyContext ): LGraphGroup[] { if (!ids?.size) return [] const docGroups = readDocGroups(doc.getMap('meta').get('groups')) const created: LGraphGroup[] = [] for (const id of ids) { this.try(context, () => { const live = graph.groups.find((group) => String(group.id) === id) const docGroup = docGroups.get(id) if (live && !docGroup) graph.remove(live) else if (!live && docGroup) created.push(addGroup(graph, docGroup)) }) } return created } private upsertNode( graph: LGraph, doc: Y.Doc, id: string, mode: ApplyMode, context: RemoteApplyContext ): 'created' | 'recreated' | 'updated' | 'skipped' { const docNode = this.readDocNode(doc, id) if (!docNode) return 'skipped' const live = graph.getNodeById(toNodeId(id)) if (live && live.type === docNode.type) { this.applyFields(live, docNode) if (docNode.widgetRecord) restoreWidgetRecord(live, docNode.widgetRecord) else this.applyWidgets(live, docNode.widgets, mode) return 'updated' } if (live) graph.remove(live) this.createNode(graph, docNode, mode, context) return live ? 'recreated' : 'created' } private createNode( graph: LGraph, docNode: DocNode, mode: ApplyMode, context: RemoteApplyContext ): LGraphNode { const node = LiteGraph.createNode(docNode.type, docNode.serialised.title) ?? missingNode(docNode) node.id = toNodeId(docNode.id) const info: ISerialisedNode = { ...docNode.serialised, inputs: docNode.serialised.inputs?.map( (input): ISerialisableNodeInput => ({ ...input }) ), outputs: docNode.serialised.outputs?.map( (output): ISerialisableNodeOutput => ({ ...output }) ) } if (docNode.widgetRecord) info.widgets_values = docNode.widgetRecord as unknown as WidgetValue[] detachSerialisedLinks(info) node.pos = [info.pos[0], info.pos[1]] graph.add(node) if (node.id !== toNodeId(docNode.id)) { const existingOwner = diagnosticNodeOwner(graph, toNodeId(docNode.id)) this.reportOnce( `node-id:${docNode.id}`, `Live graph reminted node ${docNode.id} as ${String(node.id)}`, 'agent_graph_node_id_reminted', { nodeId: docNode.id, liveId: node.id, nodeType: docNode.type, mode, ...existingOwner, ...diagnosticApplyContext(context), liveAgentTurn: context.liveAgentTurn === true } ) } if (node.has_errors) { node.last_serialization = info configureRemoteNode(node, info) } else { if (node.isSubgraphNode()) { const beforeConfigurePromotedIds = promotedWidgetIds(node) configureRemoteNode(node, info) this.applyConfiguredHostWidgets( node, docNode.widgets, beforeConfigurePromotedIds, mode ) } else { const constructed = serializableWidgets(node) const constructedNames = new Set( node.widgets?.map((widget) => widget.name) ) const deferred = deferredRowCounts(node, constructed, docNode.widgets) configureRemoteNode(node, { ...info, widgets_values: docNode.widgetRecord === undefined ? positionalWidgetValues(node, docNode.widgets, deferred) : info.widgets_values }) const mounted = mountedWidgetValues( node, docNode.widgets, constructed, constructedNames, deferred ) if (mounted) this.applyWidgets(node, mounted, mode, { documentWidgets: docNode.widgets, reportMissing: false }) } } floorSizeToContent(node) return node } private applyFields( node: LGraphNode, docNode: DocNode, keys?: ReadonlySet ): void { const source = docNode.serialised const edited = (key: string): boolean => !keys || keys.has(key) const flagsEdited = !keys || keys.has('flags') || [...keys].some((key) => key.startsWith('flags.')) if ( edited('title') && source.title !== undefined && node.title !== source.title ) node.title = source.title if (edited('mode')) this.applyMode(node, docNode) if (flagsEdited) applyFlags(node, source.flags, keys) if (edited('properties')) applyProperties(node, source.properties) applyAppearance(node, source, edited) } private applyMode(node: LGraphNode, docNode: DocNode): void { const { mode } = docNode.serialised if (node.mode === mode || node.changeMode(mode)) return this.reportOnce( `node-mode:${docNode.id}:${mode}`, `Document node ${docNode.id} rejected mode ${mode}`, 'agent_graph_node_mode_rejected', { nodeId: docNode.id, mode } ) } private readDocNode(doc: Y.Doc, id: string): DocNode | null { const read = readDocNode(doc, id) if (read === null) return null const key = `node-shape:${id}` if (!('malformed' in read)) { this.reported.delete(key) return read } if (this.reported.has(key)) return null const { classType, valueShapes, producer } = read.discriminate() this.reportOnce( key, `Document node ${id} (${classType ?? 'unknown class'}) is malformed: ${read.malformed}`, 'agent_graph_node_malformed', { nodeId: id, issues: read.malformed, classType, valueShapes, producer } ) return null } private syncFields( graph: LGraph, doc: Y.Doc, id: string, keys: ReadonlySet ): void { const docNode = this.readDocNode(doc, id) const node = graph.getNodeById(toNodeId(id)) if (!docNode || !node || node.type !== docNode.type) return this.applyFields(node, docNode, keys) } private syncWidgets( graph: LGraph, doc: Y.Doc, id: string, names: ReadonlySet | 'all', mode: ApplyMode ): void { const docNode = this.readDocNode(doc, id) const node = graph.getNodeById(toNodeId(id)) if (!docNode || !node || node.type !== docNode.type) return if (docNode.widgetRecord) { restoreWidgetRecord(node, docNode.widgetRecord) return } const widgets = docNode.widgets if (names === 'all' || Array.isArray(widgets)) { this.applyWidgets(node, widgets, mode) return } if (!widgets) return const regrown = this.regrownRows(node, Object.keys(widgets), names) this.applyWidgets( node, Object.fromEntries( Object.entries(widgets).filter( ([name]) => changed(node, name, names) || regrown.has(name) ) ), mode, { documentWidgets: widgets } ) } private regrownRows( node: LGraphNode, keys: readonly string[], names: ReadonlySet ): ReadonlySet { const regrown = new Set(this.unappliedRegrownRows.get(node)) for (const name of keys) { if (regrownRow(node, name, names)) regrown.add(name) } if (regrown.size > 0) this.unappliedRegrownRows.set(node, regrown) return regrown } private applyInteriors( graph: LGraph, doc: Y.Doc, changes: FrameChanges, context: RemoteApplyContext, mode: ApplyMode ): void { const granular = changes.interiors const full = changes.interiorDefinitions const hasGranular = granular !== undefined && granular.size > 0 const hasFull = full !== undefined && full.size > 0 if (!hasGranular && !hasFull) return const docInteriors = readSubgraphInteriorWidgets(doc) const targets = interiorSyncTargets(granular, full, docInteriors) for (const [definitionId, nodes] of targets) { this.try(context, () => this.syncDefinitionInteriors( graph, definitionId, nodes, docInteriors, mode ) ) } } private syncDefinitionInteriors( graph: LGraph, definitionId: string, nodes: ReadonlyMap | 'all'>, docInteriors: ReturnType, mode: ApplyMode ): void { const subgraph = graph.rootGraph.subgraphs.get(definitionId) if (!subgraph) return const docNodes = docInteriors.get(definitionId) if (!docNodes) return if (!this.interiorIds.has(definitionId)) { this.recordInteriorMapping( definitionId, [...docNodes.keys()], subgraph.nodes ) } for (const [nodeId, names] of nodes) { const widgets = docNodes.get(nodeId) if (widgets === undefined) continue const mapped = this.interiorIds.get(definitionId)?.get(nodeId) const live = mapped ? subgraph.getNodeById(mapped) : subgraph.getNodeById(toNodeId(nodeId)) if (!live) continue this.applyInteriorWidgets(live, widgets, names, mode) this.propagateInteriorToHosts( graph, definitionId, live, widgets, names, mode ) } } private propagateInteriorToHosts( graph: LGraph, definitionId: string, liveInterior: LGraphNode, widgets: unknown, names: ReadonlySet | 'all', mode: ApplyMode ): void { if (names === 'all') return if (widgets === undefined || Array.isArray(widgets)) return const record = widgets as Record for (const host of subgraphHostInstances(graph, definitionId)) { this.propagateInteriorToHost(host, liveInterior, record, names, mode) } } private applyInteriorWidgets( live: LGraphNode, widgets: Record | readonly unknown[], names: ReadonlySet | 'all', mode: ApplyMode ): void { if (names === 'all' || Array.isArray(widgets)) { this.applyWidgets(live, widgets as DocNode['widgets'], mode) return } const regrown = this.regrownRows(live, Object.keys(widgets), names) const filtered = Object.fromEntries( Object.entries(widgets).filter( ([name]) => names.has(name) || regrown.has(name) ) ) if (Object.keys(filtered).length === 0) return this.applyWidgets(live, filtered, mode, { documentWidgets: widgets as DocNode['widgets'] }) } private propagateInteriorToHost( host: LGraphNode, liveInterior: LGraphNode, record: Record, names: ReadonlySet, mode: ApplyMode ): void { for (const input of promotedInputs(host)) { const target = host.isSubgraphNode() ? host.resolvePromotedTarget(input.name) : undefined if (!target || target.nodeId !== liveInterior.id) continue if (!names.has(target.widgetName)) continue if (!Object.hasOwn(record, target.widgetName)) continue this.applyHostWidgets( host, { [input.name]: record[target.widgetName] }, mode ) } } /** * `options.documentWidgets` is the node's whole document map. It differs * from `widgets` on partial frames, where alias precedence still depends on * every key. Creation can suppress reports for unmatched names while still * reporting unresolved overflow aliases. */ private applyWidgets( node: LGraphNode, widgets: DocNode['widgets'], mode: ApplyMode, options: ApplyWidgetOptions = {} ): void { if (widgets === undefined) return if (node.isSubgraphNode()) { this.applyHostWidgets(node, widgets, mode) return } if (Array.isArray(widgets)) { this.applyPositionalWidgets(node, widgets) this.unappliedRegrownRows.delete(node) return } const { documentWidgets = widgets, reportMissing = true } = options let pending = ordinaryWidgetEntries(node, widgets).filter(isWidgetEntry) while (pending.length > 0) { const { resolved, unresolved } = this.applyWidgetRound( node, pending, documentWidgets ) if (!resolved) { this.reportMissingWidgets(node, unresolved, reportMissing) break } pending = unresolved } if (!Array.isArray(documentWidgets)) this.checkNestedRowCounts(node, widgets, documentWidgets) this.unappliedRegrownRows.delete(node) } private checkNestedRowCounts( node: LGraphNode, widgets: Record, documentWidgets: Record ): void { const applied = Object.entries(widgets) .filter(([name, value]) => Object.is(documentWidget(node, name)?.value, value) ) .map(([name]) => name) for (const controller of nestedGroupControllers( node, Object.keys(widgets), applied )) { const count = documentWidgets[controller.name] if (count === undefined || reachesDynamicGroupRowCount(controller, count)) continue reportRemoteDynamicGroupRowMismatch( node, count, Number(controller.value), { ...AGENT_APPLY_TAGS, outcome: 'degraded' }, 'remote_remount' ) } } private applyPositionalWidgets(node: LGraphNode, widgets: unknown[]): void { let live = serializableWidgets(node) for ( let index = 0; index < Math.min(widgets.length, live.length); index++ ) { const widget = live[index] const entry: [string, unknown] = [widget.name, widgets[index]] if (!isWidgetEntry(entry)) continue this.applyWidgetRound(node, [entry], widgets) if (!isDynamicGroupController(widget)) continue if (!reachesDynamicGroupRowCount(widget, entry[1])) return live = serializableWidgets(node) } } private applyWidgetRound( node: LGraphNode, pending: readonly [string, WidgetValue][], documentWidgets: DocNode['widgets'] ): { resolved: boolean; unresolved: [string, WidgetValue][] } { const unresolved: [string, WidgetValue][] = [] let resolved = false for (const [name, value] of pending) { if (supersededOverflowAlias(node, name, documentWidgets)) continue if (this.holdsLocalWrite(node, name, value)) continue const widget = documentWidget(node, name) if (widget === undefined) { unresolved.push([name, value]) continue } if ( widget.name !== name && this.holdsLocalWrite(node, widget.name, value) ) continue if (isDynamicGroupController(widget)) this.applyDynamicGroupRowCount(node, widget, value) else this.setWidgetValue(node, widget, value) resolved = true } return { resolved, unresolved } } private reportMissingWidgets( node: LGraphNode, unresolved: readonly [string, WidgetValue][], reportMissing: boolean ): void { for (const [name] of unresolved) { if (hiddenRowController(node, name)) continue if (selectionDependentAbsence(node, name)) continue if (reportMissing || overflowWidgetIndex(name) !== null) this.reportMissingWidget(node, name) } } private reportMissingWidget(node: LGraphNode, name: string): void { const overflowIndex = overflowWidgetIndex(name) this.reportOnce( `widget:${String(node.id)}:${name}`, `Node ${String(node.id)} (${node.type}) has no widget '${name}'`, 'agent_graph_widget_missing', { nodeId: node.id, type: node.type, name, availableWidgetNames: diagnosticWidgetNames(node.widgets ?? []), ...(overflowIndex === null ? {} : { overflowIndex, supportsDynamicWidgetOverflow: supportsDynamicWidgetOverflow(node), serializableWidgetNames: diagnosticWidgetNames( serializableWidgets(node) ) }) } ) } private applyConfiguredHostWidgets( node: LGraphNode, widgets: DocNode['widgets'], beforeConfigurePromotedIds: readonly string[], mode: ApplyMode ): void { const afterConfigurePromotedIds = promotedWidgetIds(node) if ( Array.isArray(widgets) && (widgets.length !== afterConfigurePromotedIds.length || !isEqual(beforeConfigurePromotedIds, afterConfigurePromotedIds)) ) { this.reportHostWidgetDrift( node, widgets.length, afterConfigurePromotedIds.length, mode, { beforeConfigurePromotedIds, afterConfigurePromotedIds } ) return } this.applyHostWidgets(node, widgets, mode) } private reportHostWidgetDrift( node: LGraphNode, actual: number, expected: number, mode: ApplyMode, identity?: { beforeConfigurePromotedIds: readonly string[] afterConfigurePromotedIds: readonly string[] } ): void { this.reportOnce( `host-widgets:${mode}:${String(node.id)}`, `Subgraph host ${String(node.id)} (${node.type}) carries ${actual} opaque widget values for ${expected} promoted widgets`, 'agent_graph_host_widgets_mismatch', { nodeId: node.id, type: node.type, expected, actual, mode, ...identity } ) } private applyHostWidgets( node: LGraphNode, widgets: DocNode['widgets'], mode: ApplyMode ): void { const promoted = promotedInputs(node) if (Array.isArray(widgets) && widgets.length !== promoted.length) { this.reportHostWidgetDrift(node, widgets.length, promoted.length, mode) return } for (const [name, value] of hostWidgetEntries(promoted, widgets)) { if (!isWidgetValue(value)) continue if (this.holdsLocalWrite(node, name, value)) continue const input = promoted.find((candidate) => candidate.name === name) if (!input) { this.reportOnce( `widget:${String(node.id)}:${name}`, `Subgraph host ${String(node.id)} (${node.type}) promotes no widget '${name}'`, 'agent_graph_widget_missing', { nodeId: node.id, type: node.type, name } ) continue } const widget = node.getWidgetFromSlot(input) if (!widget) { this.reportOnce( `widget:${String(node.id)}:${name}:unresolved`, `Subgraph host ${String(node.id)} (${node.type}) could not resolve promoted widget '${name}'`, 'agent_graph_widget_missing', { nodeId: node.id, type: node.type, name } ) continue } try { this.setPromotedWidgetValue(node, widget, value) } catch (error) { const options = { surface: 'agent', errorType: 'agent_graph_apply_failed', tags: { ...AGENT_APPLY_TAGS, outcome: 'degraded' }, context: { nodeId: String(node.id), widget: name } } as const reportError(error, options) } } } private holdsLocalWrite( node: LGraphNode, widget: string, docValue: WidgetValue ): boolean { return ( this.deps.holdsLocalWrite?.(String(node.id), widget, docValue) ?? false ) } private applyDynamicGroupRowCount( node: LGraphNode, widget: IBaseWidget, value: WidgetValue ) { const requested = typeof value === 'number' && Number.isFinite(value) ? Math.max(widget.options.min ?? 0, Math.trunc(value)) : null if ( requested !== null && requested > dynamicGroupRowAllocationBound(widget) ) { this.reportDynamicGroupRowMismatch(node, widget, value) return } const applied = applyRemoteDynamicGroupRowCount(node, () => this.assignWidgetValue(node, widget, value) ) if (applied && reachesDynamicGroupRowCount(widget, value)) return this.reportDynamicGroupRowMismatch(node, widget, value) } private reportDynamicGroupRowMismatch( node: LGraphNode, widget: IBaseWidget, value: WidgetValue ) { this.incrementFailureCount() reportRemoteDynamicGroupRowMismatch(node, value, Number(widget.value), { ...AGENT_APPLY_TAGS, outcome: 'degraded' }) } private setWidgetValue( node: LGraphNode, widget: IBaseWidget, value: WidgetValue ) { if (widget.type === 'button' || Object.is(widget.value, value)) return if (!(widget instanceof BaseWidget)) { this.assignWidgetValue(node, widget, value) return } const rollback = captureWidgetValue(node, widget) try { widget.setValue(value, { node, canvas: this.deps.getCanvas?.() ?? undefined }) } catch (error) { rollback() throw error } } private assignWidgetValue( node: LGraphNode, widget: IBaseWidget, value: WidgetValue ): boolean { if (widget.type === 'button') return false if (Object.is(widget.value, value)) return true const previous = widget.value const rollback = writeWidgetValue(node, widget, value) if (!widgetAcceptedValue(widget, value)) { rollback() return false } try { widget.callback?.(value, this.deps.getCanvas?.() ?? undefined, node) node.onWidgetChanged?.(widget.name, value, previous, widget) } catch (error) { rollback() throw error } node.graph?.incrementVersion() return true } private setPromotedWidgetValue( node: LGraphNode, widget: IBaseWidget, value: WidgetValue ): void { if (widget.type === 'button' || Object.is(widget.value, value)) return const previous = widget.value const callback = widget.callback function writeWithoutCallback(write: () => T): T { widget.callback = undefined try { return write() } finally { widget.callback = callback } } const rollback = writeWithoutCallback(() => writeWidgetValue(node, widget, value, false) ) try { callback?.call(widget, value, this.deps.getCanvas?.() ?? undefined, node) node.onWidgetChanged?.(widget.name, value, previous, widget) if (!Object.is(widget.value, value)) { writeWithoutCallback(() => writeWidgetValue(node, widget, value, false)) } } catch (error) { writeWithoutCallback(rollback) throw error } node.graph?.incrementVersion() } private applyLinks( graph: LGraph, doc: Y.Doc, keys: readonly string[], context: RemoteApplyContext ): void { const retry: DocLink[] = [] for (const key of keys) { const link = readDocLink(doc, key) if (!link) { const id = parseLinkId(key) if (id !== undefined) this.try(context, () => graph.removeLink(toLinkId(id))) continue } this.try(context, () => { if (this.connectLink(graph, doc, link) === 'unresolved') retry.push(link) }) } for (const link of retry) { this.try(context, () => { if (this.connectLink(graph, doc, link) !== 'connected') { this.reportOnce( `link:${link.id}`, `Link ${link.id} (node ${link.origin} slot ${link.originSlot} -> node ${link.target} slot ${link.targetSlot}) could not be connected on the live graph`, 'agent_graph_link_unresolved', { ...link } ) } }) } } private connectLink( graph: LGraph, doc: Y.Doc, link: DocLink ): 'connected' | 'present' | 'unresolved' | 'refused' | 'missing-node' { const origin = graph.getNodeById(toNodeId(link.origin)) const target = graph.getNodeById(toNodeId(link.target)) if (!origin || !target) return 'missing-node' const originSlot = resolveSlot( origin.outputs.map((output) => output.name), readDocSlotName(doc, link.origin, 'outputs', link.originSlot), link.originSlot, 'positional' ) const targetSlot = resolveTargetSlot(target, doc, link) if (originSlot < 0 || targetSlot < 0) { if (graph.links.has(link.id)) graph.removeLink(link.id) return 'unresolved' } if (isLinkPresent(graph, origin, originSlot, target, targetSlot)) return 'present' if (graph.links.has(link.id)) graph.removeLink(link.id) const created = withLinkId(graph, link.id, () => origin.connect(originSlot, target, targetSlot) ) return created ? 'connected' : 'refused' } private placeBatch( graph: LGraph, created: readonly NodeId[], createdGroups: readonly LGraphGroup[], { moveCollisions }: { moveCollisions: boolean } ): void { const createdSet = new Set(created) const rect = (item: LGraphNode | LGraphGroup): PlacementRect => ({ x: item.pos[0], y: item.pos[1], width: item.size[0], height: item.size[1] }) const createdNodes = graph._nodes.filter((node) => createdSet.has(node.id)) const existingNodes = graph._nodes.filter( (node) => !createdSet.has(node.id) ) const ctx = this.deps.getCanvas?.()?.ctx ?? undefined const existingBounds = existingNodes.map((node) => isRendered(node) ? node.boundingRect : pendingBounds(node, ctx) ) const createdBounds = createdNodes.map((node) => pendingBounds(node, ctx)) const framesOnlyExisting = (group: LGraphGroup) => framesAny(group, existingBounds) && !framesAny(group, createdBounds) const kept = createdGroups.filter(framesOnlyExisting) const placedGroups = kept.length > 0 && createdNodes.length === 0 ? [] : createdGroups.filter((group) => !kept.includes(group)) const incoming = [...createdNodes, ...placedGroups] const offset = placementOffset({ existing: [ ...existingNodes, ...graph.groups.filter((group) => !placedGroups.includes(group)) ].map(rect), viewport: this.deps.viewportBounds?.() ?? null, incoming: incoming.map(rect), moveCollisions }) if (!offset) return for (const item of incoming) { item.pos = [item.pos[0] + offset.dx, item.pos[1] + offset.dy] } } } /** True once a frame has measured the node; until then its bounds are zero. */ function isRendered(node: LGraphNode): boolean { const [, , width, height] = node.boundingRect return width > 0 || height > 0 } /** * The bounds the next frame will give a node that has not been drawn yet, * measured the way LiteGraph does it, including a collapsed node's title width. * `measure()` caches the collapsed width the node renders at; that cache is * left for the next frame to write, because without a canvas context it would * be written as zero. */ function pendingBounds( node: LGraphNode, ctx: CanvasRenderingContext2D | undefined ): ReadOnlyRect { const out: Rect = [0, 0, 0, 0] const collapsedWidth = node._collapsed_width node.measure(out, ctx) node._collapsed_width = collapsedWidth return out } function framesAny( group: LGraphGroup, bounds: readonly ReadOnlyRect[] ): boolean { return bounds.some((rect) => containsCentre(group._bounding, rect)) } function isLinkPresent( graph: LGraph, origin: LGraphNode, originSlot: number, target: LGraphNode, targetSlot: number ): boolean { const currentId = target.inputs[targetSlot]?.link const current = currentId == null ? undefined : graph.links.get(currentId) return ( current !== undefined && current.origin_id === origin.id && current.origin_slot === originSlot ) } /** Rank of a not-yet-mounted document name; past every live/overflow position. */ const MOUNTED_LAST = Number.MAX_SAFE_INTEGER /** * Apply order for a document widget map: live widgets in their positional * order, then overflow aliases by position, then names no widget carries yet. * The live order keeps a selector ahead of children it may rebuild. Unresolved * entries are retried after each round, so selectors can mount widgets at any * depth. */ function widgetEntryRank(node: LGraphNode, name: string): number { const live = serializableWidgets(node) const liveIndex = live.findIndex((widget) => widget.name === name) if (liveIndex !== -1) return liveIndex const index = overflowWidgetIndex(name) return index === null ? MOUNTED_LAST : live.length + index } function nestedGroupControllers( node: LGraphNode, written: readonly string[], applied: readonly string[] ): IBaseWidget[] { const under = (name: string, parent: string) => name.startsWith(`${parent}.`) return (node.widgets ?? []).filter( (widget) => isDynamicGroupController(widget) && !written.includes(widget.name) && applied.some((name) => under(widget.name, name)) && !written.some( (name) => !applied.includes(name) && under(widget.name, name) ) ) } function isWidgetEntry( entry: [string, unknown] ): entry is [string, WidgetValue] { return entry[1] !== undefined && isWidgetValue(entry[1]) } function ordinaryWidgetEntries( node: LGraphNode, widgets: Record ): [string, unknown][] { return Object.entries(widgets).sort( ([a], [b]) => widgetEntryRank(node, a) - widgetEntryRank(node, b) ) } function restoreWidgetRecord( node: LGraphNode, record: Record ): void { const widgets_values = record as unknown as WidgetValue[] if (node.has_errors) { const snapshot = node.last_serialization if (snapshot) node.last_serialization = { ...snapshot, widgets_values } return } configureRemoteNode(node, { ...omit(node.serialize(), ['widgets_values_named']), widgets_values }) } /** * Whether the changed-name set covers this document key, either directly or * through the live widget an overflow alias resolves to (rejected-op name sets * carry the widget's real name). */ function changed( node: LGraphNode, name: string, names: ReadonlySet ): boolean { if (names.has(name)) return true const positional = overflowWidget(node, name) return positional !== undefined && names.has(positional.name) } type InteriorSyncTargets = Map | 'all'>> function interiorSyncTargets( granular: InteriorChanges | undefined, full: ReadonlySet | undefined, docInteriors: ReturnType ): InteriorSyncTargets { const targets: InteriorSyncTargets = new Map() if (granular) { for (const [definitionId, nodes] of granular) { targets.set(definitionId, new Map(nodes)) } } if (full) { for (const definitionId of full) { const nodes = targets.get(definitionId) ?? new Map() for (const nodeId of docInteriors.get(definitionId)?.keys() ?? []) { if (!nodes.has(nodeId)) nodes.set(nodeId, 'all') } targets.set(definitionId, nodes) } } return targets } function promotedInputs(node: LGraphNode): INodeInputSlot[] { return node.inputs.filter((input) => input.widgetId) } function subgraphHostInstances( graph: LGraph, definitionId: string ): LGraphNode[] { const hosts: LGraphNode[] = [] const seen = new Set() const visit = (nodes: readonly LGraphNode[]): void => { for (const node of nodes) { if (seen.has(node)) continue seen.add(node) if (node.isSubgraphNode() && node.subgraph.id === definitionId) { hosts.push(node) } } } visit(graph.rootGraph.nodes) for (const subgraph of graph.rootGraph.subgraphs.values()) visit(subgraph.nodes) return hosts } function promotedWidgetIds(node: LGraphNode): string[] { return promotedInputs(node).flatMap((input) => input.widgetId ? [input.widgetId] : [] ) } /** Host widget values by promoted-input name; a positional list is read in promoted-input order. */ function hostWidgetEntries( promoted: readonly INodeInputSlot[], widgets: DocNode['widgets'] ): [string, unknown][] { if (Array.isArray(widgets)) return promoted.map((input, index) => [input.name, widgets[index]]) return Object.entries(widgets ?? {}) } function captureWidgetValue( node: LGraphNode, widget: IBaseWidget, mirrorProperty = true ): () => void { const previous = widget.value const property = widget.options.property if (!mirrorProperty || !property || node.properties[property] === undefined) return () => { widget.value = previous } const previousProperty = node.properties[property] return () => { widget.value = previous node.setProperty(property, previousProperty) } } function writeWidgetValue( node: LGraphNode, widget: IBaseWidget, value: WidgetValue, mirrorProperty = true ): () => void { const rollback = captureWidgetValue(node, widget, mirrorProperty) const property = widget.options.property widget.value = value if (mirrorProperty && property && node.properties[property] !== undefined) node.setProperty(property, value) return rollback } function applyFlags( node: LGraphNode, flags: INodeFlags, keys?: ReadonlySet ): void { const edited = (key: string) => !keys || keys.has('flags') || keys.has(`flags.${key}`) if (edited('collapsed') && node.collapsed !== !!flags.collapsed) node.collapse(true) if (edited('pinned') && node.pinned !== !!flags.pinned) node.pin(!!flags.pinned) for (const [key, value] of Object.entries({ ...node.flags, ...flags })) { if (['ghost', 'collapsed', 'pinned'].includes(key) || !edited(key)) continue if (key in flags) { Object.assign(node.flags, { [key]: value }) } else { Reflect.deleteProperty(node.flags, key) } } } function applyProperties( node: LGraphNode, properties: ISerialisedNode['properties'] ): void { for (const [key, value] of Object.entries(properties ?? {})) { if (node.properties[key] !== value) node.setProperty(key, value) } } function applyAppearance( node: LGraphNode, source: ISerialisedNode, edited: (key: string) => boolean ): void { const target = (key: 'color' | 'bgcolor') => edited(key) ? (source[key] ?? node[key]) : node[key] const color = target('color') const bgcolor = target('bgcolor') if (node.color !== color || node.bgcolor !== bgcolor) { const option = Object.values(LGraphCanvas.node_colors).find( (option) => option.color === color && option.bgcolor === bgcolor ) if (option) node.setColorOption(option) } for (const key of SYNCED_APPEARANCE_FIELDS.filter(edited)) { const value = source[key] if (value !== undefined && node[key] !== value) { Object.assign(node, { [key]: value }) } } } /** * The live input index a document link targets. A dynamic input slot the host * grew has no live counterpart until the node's autogrow group is grown to it, * so grow it rather than drop a link the document holds against a slot it * legitimately owns. `growAutogrowInput` refuses a name outside the node's own * groups, leaving a slot the live node really lacks unresolved as before. */ function resolveTargetSlot( target: LGraphNode, doc: Y.Doc, link: DocLink ): number { const docName = readDocSlotName(doc, link.target, 'inputs', link.targetSlot) const resolved = resolveSlot( target.inputs.map((input) => input.name), docName, link.targetSlot, 'none' ) if (resolved >= 0 || docName === undefined) return resolved return growAutogrowInput(target, docName) ?? resolved } /** * Resolves a document slot to a live slot index, by name first. `ComfyNode.configure` * keeps every document input name live (definition or extra), so an input * name the live node lacks is a real mismatch and never a positional guess. * It matches outputs by index and lets the definition's names win over the * document's, so an output resolves by position when its document name is * stale. */ function resolveSlot( liveNames: readonly string[], docName: string | undefined, docIndex: number, fallback: 'positional' | 'none' ): number { const byName = docName === undefined ? -1 : liveNames.indexOf(docName) if (byName >= 0 || (docName !== undefined && fallback === 'none')) { return byName } return docIndex < liveNames.length ? docIndex : -1 } /** * Root ids the document owns. Definitions register before the frame's root * nodes and links exist live, so id deduplication has to be told about them * or it hands a definition interior an id the root graph is about to need. */ function docRootIds(doc: Y.Doc): { nodeIds: NodeId[]; linkIds: number[] } { const nodeIds: NodeId[] = [] nodesMap(doc).forEach((_, id) => nodeIds.push(toNodeId(id))) const linkIds: number[] = [] linksMap(doc).forEach((_, key) => { const id = parseLinkId(key) if (id !== undefined) linkIds.push(id) }) return { nodeIds, linkIds } } function tryCreateSubgraph( rootGraph: LGraph, definition: ExportedSubgraph, reserved: { nodeIds: NodeId[]; linkIds: number[] } ): unknown { if (!isUuidShapedSubgraphId(definition.id)) { return new Error( `Agent subgraph definition id is not a UUID: ${definition.id}` ) } try { withNamedValuesRestore(() => rootGraph.createSubgraphs([definition], reserved) ) return undefined } catch (cause) { const halfBuilt = rootGraph.subgraphs.get(definition.id) if (halfBuilt) { try { rootGraph.releaseSubgraphs([halfBuilt]) } catch (rollbackCause) { return new AggregateError( [cause, rollbackCause], `Agent subgraph definition ${definition.id} failed to register and roll back` ) } } return cause } } /** * Definitions carry interior widget values by name * (`widgets_values_named`); `configure` only reads them while the * `namedValuesRestore` flag is set, so set it for the definition alone. */ function withNamedValuesRestore(fn: () => T): T { const previous = LiteGraph.namedValuesRestore LiteGraph.namedValuesRestore = true try { return fn() } finally { LiteGraph.namedValuesRestore = previous } }