@angflow/angular 0.0.15 → 0.0.18

package/dist/esm/lib/agent/agent-bridge.service.js

@@ -1,12 +1,32 @@
 import { Inject, Injectable, InjectionToken, Injector, Optional, effect, inject, runInInjectionContext, signal, } from '@angular/core';
+import { AgentHistory } from './history';
 import { AGENT_TOOL_SCHEMAS } from './tool-schemas';
 import * as i0 from "@angular/core";
 /** Provider token holding the user-supplied transport(s). */
 export const AGENT_TRANSPORTS = new InjectionToken('AngflowAgentTransports');
+/** Provider token for history config. `false` disables history entirely. */
+export const AGENT_HISTORY_OPTIONS = new InjectionToken('AngflowAgentHistoryOptions');
+/** Optional error sink. Receives transport/dispatch failures that the bridge swallows. */
+export const AGENT_ON_ERROR = new InjectionToken('AngflowAgentOnError');
+/** Optional host-provided layout function backing the `layout_nodes` tool. */
+export const AGENT_LAYOUT = new InjectionToken('AngflowAgentLayout');
 const ERROR_INVALID_PARAMS = -32602;
 const ERROR_METHOD_NOT_FOUND = -32601;
 const ERROR_FLOW_NOT_FOUND = -32000;
 const ERROR_INTERNAL = -32603;
+const MUTATING_TOOLS = new Set([
+    'add_node',
+    'add_nodes',
+    'add_edge',
+    'add_edges',
+    'update_node',
+    'update_node_data',
+    'update_edge',
+    'update_edge_data',
+    'delete_elements',
+    'set_nodes',
+    'set_edges',
+]);
 /**
  * Routes JSON-RPC requests from one or more transports to registered
  * `NgFlowService` instances, and pushes change events back to the agent.
@@ -32,19 +52,35 @@ const ERROR_INTERNAL = -32603;
  * ```
  */
 export class AngflowAgentBridge {
-    constructor(transports) {
+    constructor(transports, historyOptions, onError, layoutFn) {
         /** Schemas for every exposed tool — feed straight to a Claude / OpenAI tools array. */
         this.toolSchemas = AGENT_TOOL_SCHEMAS;
         this.flows = new Map();
         this.handlers = new Map();
         this.injector = inject(Injector);
         this.started = false;
+        this.nextInProcessId = 1;
+        this.warnedOnBeforeDeleteBypass = false;
         /** Bumped every time a flow registers/unregisters. Useful for diagnostics. */
         this.registeredFlows = signal([], ...(ngDevMode ? [{ debugName: "registeredFlows" }] : /* istanbul ignore next */ []));
         this.transports = transports ?? [];
+        this.history =
+            historyOptions === false ? null : new AgentHistory(historyOptions ?? undefined);
+        this.onError = onError ?? null;
+        this.layoutFn = layoutFn ?? null;
         this.installHandlers();
         this.start();
     }
+    reportError(err, ctx) {
+        if (!this.onError)
+            return;
+        try {
+            this.onError(err, ctx);
+        }
+        catch {
+            // An onError handler must not crash the bridge.
+        }
+    }
     /**
      * Register a flow under `id`. The bridge subscribes to its `nodes`,
      * `edges`, and `viewport` signals and emits change events to all
@@ -55,11 +91,21 @@ export class AngflowAgentBridge {
      * `(init)` on `<ng-flow>` and pair with `OnDestroy`.
      */
     register(id, flow) {
-        if (this.flows.has(id)) {
-            this.flows.get(id).watcher.destroy();
+        const existing = this.flows.get(id);
+        if (existing) {
+            // Idempotent re-register: same id + same service is a no-op so callers
+            // can safely call from (init) without tracking lifecycle.
+            if (existing.service === flow) {
+                return () => this.unregister(id);
+            }
+            // Different service under the same id: tear down the old watcher and
+            // drop history (the previous snapshots refer to a different graph and
+            // restoring them into this service would corrupt it).
+            existing.dispose();
+            this.history?.dropFlow(id);
         }
-        const watcher = this.watchFlow(id, flow);
-        this.flows.set(id, { service: flow, watcher });
+        const dispose = this.watchFlow(id, flow);
+        this.flows.set(id, { service: flow, dispose });
         this.registeredFlows.set(Array.from(this.flows.keys()));
         this.emit({ event: 'flow.registered', params: { flowId: id } });
         return () => this.unregister(id);
@@ -68,8 +114,9 @@ export class AngflowAgentBridge {
         const entry = this.flows.get(id);
         if (!entry)
             return;
-        entry.watcher.destroy();
+        entry.dispose();
         this.flows.delete(id);
+        this.history?.dropFlow(id);
         this.registeredFlows.set(Array.from(this.flows.keys()));
         this.emit({ event: 'flow.unregistered', params: { flowId: id } });
     }
@@ -78,20 +125,24 @@ export class AngflowAgentBridge {
         return this.flows.get(id)?.service;
     }
     /**
-     * Invoke a tool directly without going through a transport. Useful for
-     * in-process callers (tests, devtools snippets, Angular components that
-     * want to share the same dispatch logic).
+     * Invoke a tool directly without going through a transport. Behaves
+     * identically to a JSON-RPC request: captures a history snapshot, emits
+     * `flow.history` / `flow.state` events, and throws a structured error
+     * (with `code` and `data` attached) on failure.
      */
     async callTool(method, params = {}) {
-        const handler = this.handlers.get(method);
-        if (!handler) {
-            throw new Error(`Unknown tool: ${method}`);
-        }
-        if (method === 'list_flows') {
-            return handler(null, params);
+        const response = await this.dispatch({
+            id: `in-process:${this.nextInProcessId++}`,
+            method,
+            params,
+        });
+        if ('error' in response) {
+            const err = new Error(response.error.message);
+            err.code = response.error.code;
+            err.data = response.error.data;
+            throw err;
         }
-        const flow = this.resolveFlow(params['flowId']);
-        return handler(flow, params);
+        return response.result;
     }
     // ── Internals ────────────────────────────────────────────────────────
     start() {
@@ -99,7 +150,15 @@ export class AngflowAgentBridge {
             return;
         this.started = true;
         for (const t of this.transports) {
-            void t.start((req) => this.dispatch(req));
+            try {
+                const maybePromise = t.start((req) => this.dispatch(req));
+                if (maybePromise && typeof maybePromise.then === 'function') {
+                    maybePromise.catch((err) => this.reportError(err, { kind: 'transport-start', transport: t }));
+                }
+            }
+            catch (err) {
+                this.reportError(err, { kind: 'transport-start', transport: t });
+            }
         }
     }
     async dispatch(req) {
@@ -117,16 +176,74 @@ export class AngflowAgentBridge {
                 return { id: req.id, result };
             }
             const flow = this.resolveFlow(params['flowId']);
+            const flowId = this.findFlowId(flow);
+            const isApplyChanges = req.method === 'apply_changes';
+            const isLayout = req.method === 'layout_nodes';
+            // Pre-mutation snapshot for history capture. Skipped for non-mutating tools.
+            // Shallow-clone each element so subsequent in-place mutations (notably
+            // the drag fast-path in FlowStore) can't retroactively corrupt the
+            // snapshot we already captured.
+            let snapshot = null;
+            if (this.history && (MUTATING_TOOLS.has(req.method) || isApplyChanges || isLayout)) {
+                snapshot = {
+                    nodes: flow.getNodes().map((n) => ({ ...n })),
+                    edges: flow.getEdges().map((e) => ({ ...e })),
+                };
+            }
             const result = await handler(flow, params);
+            // Commit the captured snapshot to history. For apply_changes, the handler
+            // either succeeded entirely or threw and was rolled back already.
+            if (snapshot && flowId && this.history) {
+                if (isApplyChanges) {
+                    const ops = params['ops'] ?? [];
+                    const hasNonSelection = ops.some((o) => o['op'] !== 'select_nodes' &&
+                        o['op'] !== 'select_edges' &&
+                        o['op'] !== 'deselect_all');
+                    if (hasNonSelection) {
+                        this.history.capture(flowId, snapshot);
+                        this.emitHistory(flowId);
+                    }
+                }
+                else if (isLayout) {
+                    // Capture only when at least one position was applied — an empty
+                    // layout pass must not pollute the undo stack.
+                    const positions = result?.positions ?? {};
+                    if (Object.keys(positions).length > 0) {
+                        this.history.capture(flowId, snapshot);
+                        this.emitHistory(flowId);
+                    }
+                }
+                else {
+                    this.history.capture(flowId, snapshot);
+                    this.emitHistory(flowId);
+                }
+            }
             return { id: req.id, result: result ?? null };
         }
         catch (err) {
             if (err instanceof FlowNotFoundError) {
                 return { id: req.id, error: { code: ERROR_FLOW_NOT_FOUND, message: err.message } };
             }
+            if (err instanceof MethodUnavailableError) {
+                return { id: req.id, error: { code: ERROR_METHOD_NOT_FOUND, message: err.message } };
+            }
             if (err instanceof InvalidParamsError) {
                 return { id: req.id, error: { code: ERROR_INVALID_PARAMS, message: err.message } };
             }
+            if (err instanceof ApplyChangesError) {
+                return {
+                    id: req.id,
+                    error: {
+                        code: ERROR_INTERNAL,
+                        message: err.message,
+                        data: { failedIndex: err.failedIndex },
+                    },
+                };
+            }
+            // Anything that lands here is an unexpected throw inside a handler — a
+            // bug or an underlying service failure. Surface it via onError so the
+            // host can log / report it; the wire response is still -32603.
+            this.reportError(err, { kind: 'dispatch', method: req.method });
             return {
                 id: req.id,
                 error: {
@@ -136,13 +253,28 @@ export class AngflowAgentBridge {
             };
         }
     }
+    findFlowId(flow) {
+        for (const [id, entry] of this.flows.entries()) {
+            if (entry.service === flow)
+                return id;
+        }
+        return null;
+    }
+    emitHistory(flowId) {
+        if (!this.history)
+            return;
+        const status = this.history.status(flowId);
+        this.emit({ event: 'flow.history', params: { flowId, ...status } });
+    }
     emit(evt) {
         for (const t of this.transports) {
             try {
                 t.send(evt);
             }
-            catch {
-                // Transport errors are isolated per-transport; never let one break the bridge.
+            catch (err) {
+                // Transport errors are isolated per-transport; never let one break the
+                // bridge. Forward to onError if the host wants to observe them.
+                this.reportError(err, { kind: 'transport-send', transport: t });
             }
         }
     }
@@ -163,8 +295,9 @@ export class AngflowAgentBridge {
     }
     watchFlow(id, flow) {
         let pending = false;
+        let destroyed = false;
         let lastSignature = '';
-        return runInInjectionContext(this.injector, () => effect(() => {
+        const ref = runInInjectionContext(this.injector, () => effect(() => {
             // Touch every signal we want to broadcast so the effect re-runs on change.
             flow.nodes();
             flow.edges();
@@ -176,6 +309,11 @@ export class AngflowAgentBridge {
             pending = true;
             queueMicrotask(() => {
                 pending = false;
+                // A queued microtask may outlive the effect (unregister between
+                // effect run and microtask drain). Drop late emissions so we never
+                // push state for a flowId that's no longer registered.
+                if (destroyed)
+                    return;
                 // Re-read on flush so coalesced bursts see the latest state.
                 const params = {
                     flowId: id,
@@ -188,7 +326,8 @@ export class AngflowAgentBridge {
                     },
                 };
                 // Suppress duplicate emissions when controlled-mode round-trips bounce
-                // the same state through the store twice. Cheap signature: ids + counts.
+                // identical state through the store twice. See signatureOf for the
+                // field set; it must cover anything a mutating tool can change.
                 const sig = signatureOf(params);
                 if (sig === lastSignature)
                     return;
@@ -196,6 +335,10 @@ export class AngflowAgentBridge {
                 this.emit({ event: 'flow.state', params });
             });
         }));
+        return () => {
+            destroyed = true;
+            ref.destroy();
+        };
     }
     installHandlers() {
         this.handlers.set('list_flows', () => Array.from(this.flows.keys()));
@@ -215,12 +358,12 @@ export class AngflowAgentBridge {
             return flow.getEdge(id) ?? null;
         });
         this.handlers.set('add_node', (flow, params) => {
-            const node = requireObject(params, 'node');
+            const node = validateNodeShape(requireObject(params, 'node'), 'add_node');
             flow.addNodes(node);
             return flow.getNode(node.id) ?? null;
         });
         this.handlers.set('add_edge', (flow, params) => {
-            const edge = requireObject(params, 'edge');
+            const edge = validateEdgeShape(requireObject(params, 'edge'), 'add_edge');
             flow.addEdges(edge);
             return flow.getEdge(edge.id) ?? null;
         });
@@ -249,11 +392,11 @@ export class AngflowAgentBridge {
             };
         });
         this.handlers.set('set_nodes', (flow, params) => {
-            const nodes = requireArray(params, 'nodes');
+            const nodes = requireArray(params, 'nodes').map((n, i) => validateNodeShape(n, `set_nodes[${i}]`));
             flow.setNodes(nodes);
         });
         this.handlers.set('set_edges', (flow, params) => {
-            const edges = requireArray(params, 'edges');
+            const edges = requireArray(params, 'edges').map((e, i) => validateEdgeShape(e, `set_edges[${i}]`));
             flow.setEdges(edges);
         });
         this.handlers.set('fit_view', (flow, params) => {
@@ -274,11 +417,397 @@ export class AngflowAgentBridge {
             flow.setViewport(viewport, { duration });
         });
         this.handlers.set('get_viewport', (flow) => flow.getViewport());
+        this.handlers.set('get_internal_node', (flow, params) => {
+            const id = requireString(params, 'id');
+            const internal = flow.getInternalNode(id);
+            if (!internal)
+                return null;
+            return {
+                id: internal.id,
+                positionAbsolute: internal.internals?.positionAbsolute ?? internal.position,
+                measured: internal.measured
+                    ? { width: internal.measured.width, height: internal.measured.height }
+                    : null,
+                handleBounds: internal.internals?.handleBounds ?? null,
+            };
+        });
+        this.handlers.set('get_nodes_bounds', (flow, params) => {
+            const nodeIds = optionalStringArray(params, 'nodeIds');
+            const nodes = nodeIds ? flow.getNodes(nodeIds) : flow.getNodes();
+            return flow.getNodesBounds(nodes);
+        });
+        this.handlers.set('get_intersecting_nodes', (flow, params) => {
+            const id = requireString(params, 'id');
+            const partially = typeof params['partially'] === 'boolean' ? params['partially'] : true;
+            const node = flow.getNode(id);
+            if (!node)
+                return [];
+            return flow.getIntersectingNodes(node, partially);
+        });
+        this.handlers.set('is_node_in_area', (flow, params) => {
+            const id = requireString(params, 'id');
+            const area = requireObject(params, 'area');
+            const partially = typeof params['partially'] === 'boolean' ? params['partially'] : true;
+            const node = flow.getNode(id);
+            if (!node)
+                return false;
+            return flow.isNodeIntersecting(node, area, partially);
+        });
+        this.handlers.set('get_outgoers', (flow, params) => {
+            const id = requireString(params, 'id');
+            // Use the signal-based selector then read its current value to stay non-reactive at the JSON boundary.
+            return flow.selectOutgoers(id)();
+        });
+        this.handlers.set('get_incomers', (flow, params) => {
+            const id = requireString(params, 'id');
+            return flow.selectIncomers(id)();
+        });
+        this.handlers.set('get_connected_edges', (flow, params) => {
+            const nodeIds = optionalStringArray(params, 'nodeIds');
+            if (!nodeIds)
+                throw new InvalidParamsError('Param "nodeIds" must be an array of strings.');
+            return flow.getConnectedEdges(nodeIds);
+        });
+        this.handlers.set('get_node_connections', (flow, params) => {
+            const nodeId = requireString(params, 'nodeId');
+            return flow.getNodeConnections(nodeId);
+        });
+        this.handlers.set('get_handle_connections', (flow, params) => {
+            const nodeId = requireString(params, 'nodeId');
+            const type = requireString(params, 'type');
+            if (type !== 'source' && type !== 'target') {
+                throw new InvalidParamsError('Param "type" must be "source" or "target".');
+            }
+            const handleId = typeof params['handleId'] === 'string' ? params['handleId'] : undefined;
+            return flow.getHandleConnections({ nodeId, type, id: handleId });
+        });
+        this.handlers.set('get_handle_data', (flow, params) => {
+            const nodeId = requireString(params, 'nodeId');
+            const type = requireString(params, 'type');
+            if (type !== 'source' && type !== 'target') {
+                throw new InvalidParamsError('Param "type" must be "source" or "target".');
+            }
+            const rawHandleId = params['handleId'];
+            if (rawHandleId !== null && typeof rawHandleId !== 'string') {
+                throw new InvalidParamsError('Param "handleId" must be a string or null.');
+            }
+            return flow.getHandleData(nodeId, rawHandleId, type) ?? null;
+        });
+        this.handlers.set('screen_to_flow_position', (flow, params) => {
+            const position = requireObject(params, 'position');
+            const snapToGrid = typeof params['snapToGrid'] === 'boolean' ? params['snapToGrid'] : undefined;
+            return flow.screenToFlowPosition(position, snapToGrid !== undefined ? { snapToGrid } : undefined);
+        });
+        this.handlers.set('flow_to_screen_position', (flow, params) => {
+            const position = requireObject(params, 'position');
+            return flow.flowToScreenPosition(position);
+        });
+        this.handlers.set('zoom_in', (flow, params) => {
+            const duration = typeof params['duration'] === 'number' ? params['duration'] : undefined;
+            return flow.zoomIn({ duration });
+        });
+        this.handlers.set('zoom_out', (flow, params) => {
+            const duration = typeof params['duration'] === 'number' ? params['duration'] : undefined;
+            return flow.zoomOut({ duration });
+        });
+        this.handlers.set('zoom_to', (flow, params) => {
+            const level = params['level'];
+            if (typeof level !== 'number')
+                throw new InvalidParamsError('Param "level" must be a number.');
+            const duration = typeof params['duration'] === 'number' ? params['duration'] : undefined;
+            return flow.zoomTo(level, { duration });
+        });
+        this.handlers.set('set_center', (flow, params) => {
+            const x = params['x'];
+            const y = params['y'];
+            if (typeof x !== 'number' || typeof y !== 'number') {
+                throw new InvalidParamsError('Params "x" and "y" must be numbers.');
+            }
+            const zoom = typeof params['zoom'] === 'number' ? params['zoom'] : undefined;
+            const duration = typeof params['duration'] === 'number' ? params['duration'] : undefined;
+            return flow.setCenter(x, y, { zoom, duration });
+        });
+        this.handlers.set('fit_bounds', (flow, params) => {
+            const bounds = requireObject(params, 'bounds');
+            const padding = typeof params['padding'] === 'number' ? params['padding'] : undefined;
+            const duration = typeof params['duration'] === 'number' ? params['duration'] : undefined;
+            return flow.fitBounds(bounds, { padding, duration });
+        });
+        this.handlers.set('add_nodes', (flow, params) => {
+            const nodes = requireArray(params, 'nodes').map((n, i) => validateNodeShape(n, `add_nodes[${i}]`));
+            flow.addNodes(nodes);
+            return nodes.map((n) => flow.getNode(n.id)).filter((n) => !!n);
+        });
+        this.handlers.set('add_edges', (flow, params) => {
+            const edges = requireArray(params, 'edges').map((e, i) => validateEdgeShape(e, `add_edges[${i}]`));
+            flow.addEdges(edges);
+            return edges.map((e) => flow.getEdge(e.id)).filter((e) => !!e);
+        });
+        this.handlers.set('update_node_data', (flow, params) => {
+            const id = requireString(params, 'id');
+            const dataPatch = requireObject(params, 'dataPatch');
+            flow.updateNodeData(id, dataPatch);
+            return flow.getNode(id) ?? null;
+        });
+        this.handlers.set('update_edge_data', (flow, params) => {
+            const id = requireString(params, 'id');
+            const dataPatch = requireObject(params, 'dataPatch');
+            flow.updateEdgeData(id, dataPatch);
+            return flow.getEdge(id) ?? null;
+        });
+        this.handlers.set('select_nodes', (flow, params) => {
+            const nodeIds = optionalStringArray(params, 'nodeIds');
+            if (!nodeIds)
+                throw new InvalidParamsError('Param "nodeIds" must be an array of strings.');
+            const additive = typeof params['additive'] === 'boolean' ? params['additive'] : false;
+            flow.setSelection({ nodeIds, additive });
+            return { selectedNodeIds: flow.selectedNodes().map((n) => n.id) };
+        });
+        this.handlers.set('select_edges', (flow, params) => {
+            const edgeIds = optionalStringArray(params, 'edgeIds');
+            if (!edgeIds)
+                throw new InvalidParamsError('Param "edgeIds" must be an array of strings.');
+            const additive = typeof params['additive'] === 'boolean' ? params['additive'] : false;
+            flow.setSelection({ edgeIds, additive });
+            return { selectedEdgeIds: flow.selectedEdges().map((e) => e.id) };
+        });
+        this.handlers.set('deselect_all', (flow) => {
+            flow.setSelection({ nodeIds: [], edgeIds: [], additive: false });
+        });
+        this.handlers.set('apply_changes', (flow, params) => {
+            const ops = requireArray(params, 'ops');
+            // apply_changes' delete_elements op takes the synchronous setNodes/
+            // setEdges path so the whole batch can roll back, which means
+            // onBeforeDelete is bypassed (it can't be awaited inside a rollback-
+            // capable batch). Warn once per bridge lifetime if the host actually
+            // has the veto hook registered — otherwise the silent veto-loss is
+            // very hard to discover.
+            if (!this.warnedOnBeforeDeleteBypass && flow.hasOnBeforeDeleteHook()) {
+                const hasDelete = ops.some((o) => o['op'] === 'delete_elements');
+                if (hasDelete) {
+                    this.warnedOnBeforeDeleteBypass = true;
+                    // eslint-disable-next-line no-console
+                    console.warn('[angflow] apply_changes/delete_elements bypasses onBeforeDelete. ' +
+                        'Call the standalone `delete_elements` tool if you need the veto hook.');
+                }
+            }
+            // Capture snapshot for rollback. Viewport is intentionally excluded.
+            // Shallow-clone each element so in-place field assignments (e.g.
+            // FlowStore's drag fast-path writing `node.position` / `node.dragging`)
+            // cannot corrupt the snapshot mid-batch. We do not deep-clone `data`
+            // because mutating `data` directly violates the documented contract.
+            const snapshot = {
+                nodes: flow.getNodes().map((n) => ({ ...n })),
+                edges: flow.getEdges().map((e) => ({ ...e })),
+            };
+            const results = [];
+            let failure = null;
+            flow.batch(() => {
+                for (let i = 0; i < ops.length; i++) {
+                    try {
+                        results.push({ ok: true, value: executeOp(flow, ops[i]) });
+                    }
+                    catch (err) {
+                        failure = { failedIndex: i, cause: err };
+                        break;
+                    }
+                }
+            });
+            if (failure) {
+                flow.batch(() => {
+                    flow.setNodes(snapshot.nodes);
+                    flow.setEdges(snapshot.edges);
+                });
+                const f = failure;
+                const message = f.cause instanceof Error ? f.cause.message : String(f.cause);
+                throw new ApplyChangesError(f.failedIndex, message);
+            }
+            return { results };
+        });
+        this.handlers.set('undo', (flow, params) => {
+            if (!this.history)
+                return { undone: 0, canUndo: false, canRedo: false };
+            const flowId = this.findFlowId(flow);
+            if (!flowId)
+                return { undone: 0, canUndo: false, canRedo: false };
+            const steps = typeof params['steps'] === 'number' ? params['steps'] : 1;
+            const current = {
+                nodes: flow.getNodes().map((n) => ({ ...n })),
+                edges: flow.getEdges().map((e) => ({ ...e })),
+            };
+            const result = this.history.undo(flowId, steps, current);
+            if (result) {
+                flow.batch(() => {
+                    flow.setNodes(result.snapshot.nodes);
+                    flow.setEdges(result.snapshot.edges);
+                });
+            }
+            this.emitHistory(flowId);
+            const status = this.history.status(flowId);
+            return { undone: result?.consumed ?? 0, canUndo: status.canUndo, canRedo: status.canRedo };
+        });
+        this.handlers.set('redo', (flow, params) => {
+            if (!this.history)
+                return { redone: 0, canUndo: false, canRedo: false };
+            const flowId = this.findFlowId(flow);
+            if (!flowId)
+                return { redone: 0, canUndo: false, canRedo: false };
+            const steps = typeof params['steps'] === 'number' ? params['steps'] : 1;
+            const current = {
+                nodes: flow.getNodes().map((n) => ({ ...n })),
+                edges: flow.getEdges().map((e) => ({ ...e })),
+            };
+            const result = this.history.redo(flowId, steps, current);
+            if (result) {
+                flow.batch(() => {
+                    flow.setNodes(result.snapshot.nodes);
+                    flow.setEdges(result.snapshot.edges);
+                });
+            }
+            this.emitHistory(flowId);
+            const status = this.history.status(flowId);
+            return { redone: result?.consumed ?? 0, canUndo: status.canUndo, canRedo: status.canRedo };
+        });
+        this.handlers.set('history_status', (flow) => {
+            if (!this.history)
+                return { canUndo: false, canRedo: false, pastDepth: 0, futureDepth: 0 };
+            const flowId = this.findFlowId(flow);
+            if (!flowId)
+                return { canUndo: false, canRedo: false, pastDepth: 0, futureDepth: 0 };
+            return this.history.status(flowId);
+        });
+        this.handlers.set('clear_history', (flow) => {
+            if (!this.history)
+                return;
+            const flowId = this.findFlowId(flow);
+            if (!flowId)
+                return;
+            this.history.clear(flowId);
+            this.emitHistory(flowId);
+        });
+        this.handlers.set('list_node_types', (flow) => ({ types: flow.getNodeTypeNames() }));
+        this.handlers.set('list_edge_types', (flow) => ({ types: flow.getEdgeTypeNames() }));
+        this.handlers.set('register_node_template', (flow, params) => {
+            const name = requireString(params, 'name');
+            if (name.length === 0) {
+                throw new InvalidParamsError('Param "name" must be a non-empty string.');
+            }
+            const spec = validateTemplateSpec(requireObject(params, 'spec'), 'register_node_template');
+            const claimed = flow
+                .getNodeTypeNames()
+                .find((t) => t.name === name && t.source !== 'template');
+            if (claimed) {
+                throw new InvalidParamsError(`register_node_template: "${name}" is already registered by the ` +
+                    `${claimed.source === 'builtin' ? 'library' : 'host application'} and cannot be overridden.`);
+            }
+            flow.registerNodeTemplate(name, spec);
+            return { name };
+        });
+        this.handlers.set('unregister_node_template', (flow, params) => {
+            const name = requireString(params, 'name');
+            return { removed: flow.unregisterNodeTemplate(name) };
+        });
+        this.handlers.set('list_node_templates', (flow) => ({
+            templates: flow.getNodeTemplates(),
+        }));
+        this.handlers.set('layout_nodes', async (flow, params) => {
+            if (!this.layoutFn) {
+                throw new MethodUnavailableError('layout_nodes unavailable: no layout function configured. ' +
+                    'Pass `layout` to provideAgentBridge (e.g. dagreLayout from @angflow/angular/layout).');
+            }
+            const direction = params['direction'] ?? 'TB';
+            if (typeof direction !== 'string' || !['TB', 'LR', 'BT', 'RL'].includes(direction)) {
+                throw new InvalidParamsError('Param "direction" must be one of: TB, LR, BT, RL.');
+            }
+            const nodeSep = typeof params['nodeSep'] === 'number' ? params['nodeSep'] : undefined;
+            const rankSep = typeof params['rankSep'] === 'number' ? params['rankSep'] : undefined;
+            const nodeIds = optionalStringArray(params, 'nodeIds');
+            if (nodeIds) {
+                for (const id of nodeIds) {
+                    if (!flow.getNode(id)) {
+                        throw new InvalidParamsError(`Param "nodeIds" contains unknown node id "${id}".`);
+                    }
+                }
+            }
+            const targetNodes = nodeIds
+                ? nodeIds.map((id) => flow.getNode(id))
+                : flow.getNodes();
+            const idSet = new Set(targetNodes.map((n) => n.id));
+            const layoutNodes = targetNodes.map((n) => {
+                const internal = flow.getInternalNode(n.id);
+                return {
+                    id: n.id,
+                    width: internal?.measured?.width ?? n.width ?? 150,
+                    height: internal?.measured?.height ?? n.height ?? 40,
+                    position: { x: n.position.x, y: n.position.y },
+                };
+            });
+            // Induced subgraph: only edges with BOTH endpoints in the target set.
+            const layoutEdges = flow
+                .getEdges()
+                .filter((e) => idSet.has(e.source) && idSet.has(e.target))
+                .map((e) => ({ source: e.source, target: e.target }));
+            const raw = await this.layoutFn(layoutNodes, layoutEdges, {
+                direction: direction,
+                nodeSep,
+                rankSep,
+            });
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new Error('layout function must return an object map of nodeId -> {x, y}.');
+            }
+            // Validate the full result BEFORE applying anything so a bad position
+            // rolls back cleanly (nothing applied, no history entry).
+            const applied = {};
+            const unknownIds = [];
+            for (const [id, pos] of Object.entries(raw)) {
+                if (!idSet.has(id)) {
+                    unknownIds.push(id);
+                    continue;
+                }
+                if (!pos ||
+                    typeof pos.x !== 'number' ||
+                    typeof pos.y !== 'number' ||
+                    !Number.isFinite(pos.x) ||
+                    !Number.isFinite(pos.y)) {
+                    throw new Error(`layout function returned an invalid position for node "${id}"`);
+                }
+                applied[id] = { x: pos.x, y: pos.y };
+            }
+            if (unknownIds.length > 0) {
+                // eslint-disable-next-line no-console
+                console.warn(`[angflow] layout_nodes: layout function returned positions for unknown node ids ` +
+                    `(ignored): ${unknownIds.join(', ')}`);
+            }
+            // Re-check existence at apply time: the graph may have changed while the
+            // (possibly async) layout fn ran — e.g. a human deleted a node. Only
+            // nodes that still exist are moved, reported, and counted for history.
+            const actuallyApplied = {};
+            for (const [id, position] of Object.entries(applied)) {
+                if (!flow.getNode(id))
+                    continue;
+                actuallyApplied[id] = position;
+            }
+            // Honors the host's [animate] input: positions tween when it's on, and
+            // the await keeps the subsequent fitView measuring settled positions.
+            await flow.setNodePositions(actuallyApplied);
+            const shouldFit = params['fitView'] !== false;
+            if (shouldFit && Object.keys(actuallyApplied).length > 0) {
+                try {
+                    await flow.fitView({});
+                }
+                catch (err) {
+                    // Best-effort viewport fit: never fail the tool over a cosmetic step,
+                    // but surface the error to hosts observing onError.
+                    this.reportError(err, { kind: 'dispatch', method: 'layout_nodes' });
+                }
+            }
+            return { positions: actuallyApplied };
+        });
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: AngflowAgentBridge, deps: [{ token: AGENT_TRANSPORTS, optional: true }], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: AngflowAgentBridge, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.15", ngImport: i0, type: AngflowAgentBridge, deps: [{ token: AGENT_TRANSPORTS, optional: true }, { token: AGENT_HISTORY_OPTIONS, optional: true }, { token: AGENT_ON_ERROR, optional: true }, { token: AGENT_LAYOUT, optional: true }], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.15", ngImport: i0, type: AngflowAgentBridge, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: AngflowAgentBridge, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.15", ngImport: i0, type: AngflowAgentBridge, decorators: [{
             type: Injectable,
             args: [{ providedIn: 'root' }]
         }], ctorParameters: () => [{ type: undefined, decorators: [{
@@ -286,19 +815,197 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.6", ngImpor
                 }, {
                     type: Inject,
                     args: [AGENT_TRANSPORTS]
+                }] }, { type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [AGENT_HISTORY_OPTIONS]
+                }] }, { type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [AGENT_ON_ERROR]
+                }] }, { type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [AGENT_LAYOUT]
                 }] }] });
 class FlowNotFoundError extends Error {
 }
 class InvalidParamsError extends Error {
 }
+/** Tool exists in the catalog but the deployment lacks a required capability. Maps to -32601. */
+class MethodUnavailableError extends Error {
+}
+class ApplyChangesError extends Error {
+    constructor(failedIndex, message) {
+        super(message);
+        this.failedIndex = failedIndex;
+    }
+}
+/**
+ * Build a stable signature of the emit payload, used to suppress duplicate
+ * emissions when controlled-mode round-trips bounce identical state through
+ * the store twice. Must hash every field that can change via a mutating
+ * tool — including `data`, `style`, `type`, `hidden`, `animated`, `label` —
+ * otherwise `update_node_data` / `update_edge_data` updates would be silently
+ * dropped.
+ */
 function signatureOf(params) {
-    const n = params.nodes
-        .map((n) => `${n.id}:${n.position.x},${n.position.y}:${n.measured?.width ?? '-'}x${n.measured?.height ?? '-'}`)
-        .join('|');
-    const e = params.edges.map((e) => `${e.id}:${e.source}>${e.target}`).join('|');
-    const v = `${params.viewport.x},${params.viewport.y},${params.viewport.zoom}`;
-    const s = `${params.selection.nodeIds.join(',')}/${params.selection.edgeIds.join(',')}`;
-    return `${n}#${e}#${v}#${s}`;
+    // Curated subset of node/edge fields that surface in `flow.state` consumers
+    // (renderers, history, agents). Order is fixed by the literal so JSON.stringify
+    // produces a deterministic string.
+    const n = params.nodes.map((node) => ({
+        id: node.id,
+        p: [node.position.x, node.position.y],
+        m: node.measured ? [node.measured.width ?? null, node.measured.height ?? null] : null,
+        t: node.type ?? null,
+        h: node.hidden === true,
+        d: node.data ?? null,
+        s: node.style ?? null,
+    }));
+    const e = params.edges.map((edge) => ({
+        id: edge.id,
+        src: edge.source,
+        tgt: edge.target,
+        sh: edge.sourceHandle ?? null,
+        th: edge.targetHandle ?? null,
+        t: edge.type ?? null,
+        h: edge.hidden === true,
+        a: edge.animated === true,
+        l: edge.label ?? null,
+        d: edge.data ?? null,
+        s: edge.style ?? null,
+    }));
+    try {
+        return JSON.stringify({ n, e, v: params.viewport, sel: params.selection });
+    }
+    catch {
+        // Defensive: if any field is non-serializable (e.g. cyclic data), fall back
+        // to a coarser signature so dedup never silently swallows updates.
+        return `__nonserializable__:${Date.now()}:${Math.random()}`;
+    }
+}
+function executeOp(flow, op) {
+    const kind = op['op'];
+    switch (kind) {
+        case 'add_node': {
+            const node = validateNodeShape(op['node'], 'apply_changes/add_node');
+            flow.addNodes(node);
+            return flow.getNode(node.id) ?? null;
+        }
+        case 'add_nodes': {
+            const nodes = op['nodes'];
+            if (!Array.isArray(nodes))
+                throw new InvalidParamsError('add_nodes: "nodes" must be an array.');
+            const validated = nodes.map((n, i) => validateNodeShape(n, `apply_changes/add_nodes[${i}]`));
+            flow.addNodes(validated);
+            return validated.map((n) => flow.getNode(n.id)).filter((n) => !!n);
+        }
+        case 'add_edge': {
+            const edge = validateEdgeShape(op['edge'], 'apply_changes/add_edge');
+            flow.addEdges(edge);
+            return flow.getEdge(edge.id) ?? null;
+        }
+        case 'add_edges': {
+            const edges = op['edges'];
+            if (!Array.isArray(edges))
+                throw new InvalidParamsError('add_edges: "edges" must be an array.');
+            const validated = edges.map((e, i) => validateEdgeShape(e, `apply_changes/add_edges[${i}]`));
+            flow.addEdges(validated);
+            return validated.map((e) => flow.getEdge(e.id)).filter((e) => !!e);
+        }
+        case 'update_node': {
+            const id = op['id'];
+            const patch = op['patch'];
+            if (typeof id !== 'string')
+                throw new InvalidParamsError('update_node: "id" must be a string.');
+            if (!patch || typeof patch !== 'object')
+                throw new InvalidParamsError('update_node: "patch" must be an object.');
+            if (!flow.getNode(id))
+                throw new InvalidParamsError(`update_node: node "${id}" not found.`);
+            flow.updateNode(id, patch);
+            return flow.getNode(id) ?? null;
+        }
+        case 'update_node_data': {
+            const id = op['id'];
+            const dataPatch = op['dataPatch'];
+            if (typeof id !== 'string')
+                throw new InvalidParamsError('update_node_data: "id" must be a string.');
+            if (!dataPatch || typeof dataPatch !== 'object')
+                throw new InvalidParamsError('update_node_data: "dataPatch" must be an object.');
+            if (!flow.getNode(id))
+                throw new InvalidParamsError(`update_node_data: node "${id}" not found.`);
+            flow.updateNodeData(id, dataPatch);
+            return flow.getNode(id) ?? null;
+        }
+        case 'update_edge': {
+            const id = op['id'];
+            const patch = op['patch'];
+            if (typeof id !== 'string')
+                throw new InvalidParamsError('update_edge: "id" must be a string.');
+            if (!patch || typeof patch !== 'object')
+                throw new InvalidParamsError('update_edge: "patch" must be an object.');
+            if (!flow.getEdge(id))
+                throw new InvalidParamsError(`update_edge: edge "${id}" not found.`);
+            flow.updateEdge(id, patch);
+            return flow.getEdge(id) ?? null;
+        }
+        case 'update_edge_data': {
+            const id = op['id'];
+            const dataPatch = op['dataPatch'];
+            if (typeof id !== 'string')
+                throw new InvalidParamsError('update_edge_data: "id" must be a string.');
+            if (!dataPatch || typeof dataPatch !== 'object')
+                throw new InvalidParamsError('update_edge_data: "dataPatch" must be an object.');
+            if (!flow.getEdge(id))
+                throw new InvalidParamsError(`update_edge_data: edge "${id}" not found.`);
+            flow.updateEdgeData(id, dataPatch);
+            return flow.getEdge(id) ?? null;
+        }
+        case 'delete_elements': {
+            const nodeIds = Array.isArray(op['nodeIds']) ? op['nodeIds'] : [];
+            const edgeIds = Array.isArray(op['edgeIds']) ? op['edgeIds'] : [];
+            // deleteElements is async because of onBeforeDelete; inside apply_changes we
+            // intentionally do not await — the synchronous setNodes/setEdges paths are
+            // what we need for rollback semantics. Skip onBeforeDelete hooks inside batches.
+            const allEdgeIds = new Set(edgeIds);
+            for (const e of flow.getEdges()) {
+                if (nodeIds.includes(e.source) || nodeIds.includes(e.target))
+                    allEdgeIds.add(e.id);
+            }
+            if (nodeIds.length > 0) {
+                flow.setNodes(flow.getNodes().filter((n) => !nodeIds.includes(n.id)));
+            }
+            if (allEdgeIds.size > 0) {
+                flow.setEdges(flow.getEdges().filter((e) => !allEdgeIds.has(e.id)));
+            }
+            return { deletedNodeIds: nodeIds, deletedEdgeIds: Array.from(allEdgeIds) };
+        }
+        case 'select_nodes': {
+            const nodeIds = op['nodeIds'];
+            if (!Array.isArray(nodeIds))
+                throw new InvalidParamsError('select_nodes: "nodeIds" must be an array.');
+            const additive = typeof op['additive'] === 'boolean' ? op['additive'] : false;
+            flow.setSelection({ nodeIds: nodeIds, additive });
+            return null;
+        }
+        case 'select_edges': {
+            const edgeIds = op['edgeIds'];
+            if (!Array.isArray(edgeIds))
+                throw new InvalidParamsError('select_edges: "edgeIds" must be an array.');
+            const additive = typeof op['additive'] === 'boolean' ? op['additive'] : false;
+            flow.setSelection({ edgeIds: edgeIds, additive });
+            return null;
+        }
+        case 'deselect_all': {
+            flow.setSelection({ nodeIds: [], edgeIds: [], additive: false });
+            return null;
+        }
+        default:
+            throw new InvalidParamsError(`Unknown op kind: ${String(kind)}`);
+    }
 }
 function requireString(params, key) {
     const value = params[key];
@@ -328,4 +1035,124 @@ function optionalStringArray(params, key) {
     }
     return value;
 }
+const BADGE_COLOR_SET = new Set(['slate', 'indigo', 'emerald', 'amber', 'rose']);
+const HANDLE_POSITION_SET = new Set(['top', 'right', 'bottom', 'left']);
+const KNOWN_SPEC_KEYS = new Set(['title', 'icon', 'accent', 'variant', 'badges', 'fields', 'body', 'handles']);
+/** Validate a NodeTemplateSpec payload. Throws InvalidParamsError naming the offending field. */
+function validateTemplateSpec(value, ctx) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new InvalidParamsError(`${ctx}: spec must be an object.`);
+    }
+    const s = value;
+    for (const key of Object.keys(s)) {
+        if (!KNOWN_SPEC_KEYS.has(key)) {
+            throw new InvalidParamsError(`${ctx}: unknown spec key "${key}".`);
+        }
+    }
+    for (const key of ['title', 'icon', 'accent', 'body']) {
+        if (s[key] !== undefined && typeof s[key] !== 'string') {
+            throw new InvalidParamsError(`${ctx}: spec.${key} must be a string.`);
+        }
+    }
+    if (s['variant'] !== undefined && s['variant'] !== 'compact' && s['variant'] !== 'detailed') {
+        throw new InvalidParamsError(`${ctx}: spec.variant must be "compact" or "detailed".`);
+    }
+    if (s['badges'] !== undefined) {
+        if (!Array.isArray(s['badges']))
+            throw new InvalidParamsError(`${ctx}: spec.badges must be an array.`);
+        s['badges'].forEach((raw, i) => {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new InvalidParamsError(`${ctx}: spec.badges[${i}] must be an object.`);
+            }
+            const b = raw;
+            if (typeof b['text'] !== 'string') {
+                throw new InvalidParamsError(`${ctx}: spec.badges[${i}].text must be a string.`);
+            }
+            if (b['color'] !== undefined && !BADGE_COLOR_SET.has(b['color'])) {
+                throw new InvalidParamsError(`${ctx}: spec.badges[${i}].color must be one of: ${Array.from(BADGE_COLOR_SET).join(', ')}.`);
+            }
+            if (b['showIf'] !== undefined && typeof b['showIf'] !== 'string') {
+                throw new InvalidParamsError(`${ctx}: spec.badges[${i}].showIf must be a string.`);
+            }
+        });
+    }
+    if (s['fields'] !== undefined) {
+        if (!Array.isArray(s['fields']))
+            throw new InvalidParamsError(`${ctx}: spec.fields must be an array.`);
+        s['fields'].forEach((raw, i) => {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new InvalidParamsError(`${ctx}: spec.fields[${i}] must be an object.`);
+            }
+            const f = raw;
+            if (typeof f['label'] !== 'string') {
+                throw new InvalidParamsError(`${ctx}: spec.fields[${i}].label must be a string.`);
+            }
+            if (typeof f['value'] !== 'string') {
+                throw new InvalidParamsError(`${ctx}: spec.fields[${i}].value must be a string.`);
+            }
+            if (f['showIf'] !== undefined && typeof f['showIf'] !== 'string') {
+                throw new InvalidParamsError(`${ctx}: spec.fields[${i}].showIf must be a string.`);
+            }
+        });
+    }
+    if (s['handles'] !== undefined) {
+        if (!Array.isArray(s['handles']))
+            throw new InvalidParamsError(`${ctx}: spec.handles must be an array.`);
+        s['handles'].forEach((raw, i) => {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new InvalidParamsError(`${ctx}: spec.handles[${i}] must be an object.`);
+            }
+            const h = raw;
+            if (h['type'] !== 'source' && h['type'] !== 'target') {
+                throw new InvalidParamsError(`${ctx}: spec.handles[${i}].type must be "source" or "target".`);
+            }
+            if (h['position'] !== undefined && !HANDLE_POSITION_SET.has(h['position'])) {
+                throw new InvalidParamsError(`${ctx}: spec.handles[${i}].position must be one of: top, right, bottom, left.`);
+            }
+            if (h['id'] !== undefined && typeof h['id'] !== 'string') {
+                throw new InvalidParamsError(`${ctx}: spec.handles[${i}].id must be a string.`);
+            }
+        });
+    }
+    return value;
+}
+/** Validate that `value` is a structurally valid Node payload for add_*. */
+function validateNodeShape(value, ctx) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new InvalidParamsError(`${ctx}: node must be an object.`);
+    }
+    const n = value;
+    if (typeof n['id'] !== 'string' || n['id'].length === 0) {
+        throw new InvalidParamsError(`${ctx}: node.id must be a non-empty string.`);
+    }
+    const pos = n['position'];
+    if (!pos || typeof pos !== 'object' || Array.isArray(pos)) {
+        throw new InvalidParamsError(`${ctx}: node.position must be { x, y }.`);
+    }
+    const p = pos;
+    if (typeof p['x'] !== 'number' || typeof p['y'] !== 'number') {
+        throw new InvalidParamsError(`${ctx}: node.position.{x,y} must be numbers.`);
+    }
+    if (!Number.isFinite(p['x']) || !Number.isFinite(p['y'])) {
+        throw new InvalidParamsError(`${ctx}: node.position.{x,y} must be finite (no NaN/Infinity).`);
+    }
+    return value;
+}
+/** Validate that `value` is a structurally valid Edge payload for add_*. */
+function validateEdgeShape(value, ctx) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new InvalidParamsError(`${ctx}: edge must be an object.`);
+    }
+    const e = value;
+    if (typeof e['id'] !== 'string' || e['id'].length === 0) {
+        throw new InvalidParamsError(`${ctx}: edge.id must be a non-empty string.`);
+    }
+    if (typeof e['source'] !== 'string' || e['source'].length === 0) {
+        throw new InvalidParamsError(`${ctx}: edge.source must be a non-empty string.`);
+    }
+    if (typeof e['target'] !== 'string' || e['target'].length === 0) {
+        throw new InvalidParamsError(`${ctx}: edge.target must be a non-empty string.`);
+    }
+    return value;
+}
 //# sourceMappingURL=agent-bridge.service.js.map