@angflow/angular 0.3.6 → 0.3.8

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

@@ -1,5 +1,6 @@
 import { DestroyRef, Inject, Injectable, InjectionToken, Injector, Optional, effect, inject, runInInjectionContext, signal, } from '@angular/core';
 import { AgentHistory } from './history';
+import { OpLog } from './op-log';
 import { AGENT_TOOL_SCHEMAS } from './tool-schemas';
 import * as i0 from "@angular/core";
 /** Provider token holding the user-supplied transport(s). */
@@ -10,10 +11,17 @@ export const AGENT_HISTORY_OPTIONS = new InjectionToken('AngflowAgentHistoryOpti
 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');
+/** Optional host write-guard for mutating tools. */
+export const AGENT_CAN_MUTATE = new InjectionToken('AngflowAgentCanMutate');
+/** Optional sink receiving each applied mutating op (for host persistence/replay). */
+export const AGENT_ON_OP = new InjectionToken('AngflowAgentOnOp');
+/** Op-log config. `false` disables the op-log + get_changes_since. Default { maxOps: 1000 }. */
+export const AGENT_OPLOG_OPTIONS = new InjectionToken('AngflowAgentOpLogOptions');
 const ERROR_INVALID_PARAMS = -32602;
 const ERROR_METHOD_NOT_FOUND = -32601;
 const ERROR_FLOW_NOT_FOUND = -32000;
 const ERROR_INTERNAL = -32603;
+const ERROR_MUTATION_DENIED = -32001;
 const MUTATING_TOOLS = new Set([
     'add_node',
     'add_nodes',
@@ -26,8 +34,16 @@ const MUTATING_TOOLS = new Set([
     'delete_elements',
     'set_nodes',
     'set_edges',
+    'group_nodes',
+    'set_node_group',
+    'set_group_collapsed',
+    'dissolve_group',
 ]);
 // apply_changes is treated specially — see dispatch logic.
+// Tools that mutate the node-template registry. They change rendering state but
+// not graph nodes/edges, so they are canMutate-gated and op-logged, but NOT put
+// through the graph-history snapshot (an undo can't restore a template).
+const TEMPLATE_TOOLS = new Set(['register_node_template', 'unregister_node_template']);
 /** Max flow.state emission rate while any node drag is in progress. */
 const DRAG_STATE_EMIT_INTERVAL_MS = 100;
 /**
@@ -55,7 +71,7 @@ const DRAG_STATE_EMIT_INTERVAL_MS = 100;
  * ```
  */
 export class AngflowAgentBridge {
-    constructor(transports, historyOptions, onError, layoutFn) {
+    constructor(transports, historyOptions, onError, layoutFn, canMutate, onOp, opLogOptions) {
         /** Schemas for every exposed tool — feed straight to a Claude / OpenAI tools array. */
         this.toolSchemas = AGENT_TOOL_SCHEMAS;
         this.flows = new Map();
@@ -64,6 +80,8 @@ export class AngflowAgentBridge {
         this.destroyRef = inject(DestroyRef);
         this.started = false;
         this.nextInProcessId = 1;
+        // Shared across flows; mintId's per-flow collision check guarantees uniqueness.
+        this.nextNodeIdSeq = 0;
         this.warnedOnBeforeDeleteBypass = false;
         /** Bumped every time a flow registers/unregisters. Useful for diagnostics. */
         this.registeredFlows = signal([], ...(ngDevMode ? [{ debugName: "registeredFlows" }] : /* istanbul ignore next */ []));
@@ -72,6 +90,9 @@ export class AngflowAgentBridge {
             historyOptions === false ? null : new AgentHistory(historyOptions ?? undefined);
         this.onError = onError ?? null;
         this.layoutFn = layoutFn ?? null;
+        this.canMutate = canMutate ?? null;
+        this.onOp = onOp ?? null;
+        this.opLog = opLogOptions === false ? null : new OpLog(opLogOptions ?? undefined);
         this.installHandlers();
         this.start();
         this.destroyRef.onDestroy(() => this.stop());
@@ -108,6 +129,7 @@ export class AngflowAgentBridge {
             // restoring them into this service would corrupt it).
             existing.dispose();
             this.history?.dropFlow(id);
+            this.opLog?.dropFlow(id);
         }
         const dispose = this.watchFlow(id, flow);
         this.flows.set(id, { service: flow, dispose });
@@ -122,6 +144,7 @@ export class AngflowAgentBridge {
         entry.dispose();
         this.flows.delete(id);
         this.history?.dropFlow(id);
+        this.opLog?.dropFlow(id);
         this.registeredFlows.set(Array.from(this.flows.keys()));
         this.emit({ event: 'flow.unregistered', params: { flowId: id } });
     }
@@ -129,17 +152,26 @@ export class AngflowAgentBridge {
     getFlow(id) {
         return this.flows.get(id)?.service;
     }
+    /** Mint a unique node/group id for a flow (collision-safe vs agent-supplied ids). */
+    mintId(flow, prefix) {
+        let id;
+        do {
+            id = `${prefix}_${++this.nextNodeIdSeq}`;
+        } while (flow.getNode(id));
+        return id;
+    }
     /**
      * 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 = {}) {
+    async callTool(method, params = {}, opts) {
         const response = await this.dispatch({
             id: `in-process:${this.nextInProcessId++}`,
             method,
             params,
+            source: opts?.source,
         });
         if ('error' in response) {
             const err = new Error(response.error.message);
@@ -199,6 +231,25 @@ export class AngflowAgentBridge {
             const flowId = this.findFlowId(flow);
             const isApplyChanges = req.method === 'apply_changes';
             const isLayout = req.method === 'layout_nodes';
+            // The guarded/recorded set: forward graph mutations only. Reads, selection,
+            // viewport, and undo/redo/clear_history are intentionally NOT gated — the
+            // guard protects against agent writes, not the host's own recovery ops.
+            const isMutating = MUTATING_TOOLS.has(req.method) || isApplyChanges || isLayout;
+            const isTemplateMutation = TEMPLATE_TOOLS.has(req.method);
+            const source = req.source;
+            if (this.canMutate && (isMutating || isTemplateMutation)) {
+                let verdict;
+                try {
+                    verdict = await this.canMutate({ method: req.method, params }, source);
+                }
+                catch (err) {
+                    this.reportError(err, { kind: 'dispatch', method: req.method });
+                    verdict = false; // fail safe
+                }
+                if (verdict !== true) {
+                    throw new MutationDeniedError(typeof verdict === 'string' && verdict ? verdict : 'Mutation denied by host.');
+                }
+            }
             // 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
@@ -211,32 +262,34 @@ export class AngflowAgentBridge {
                 };
             }
             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) {
+            // Whether this call counts as a recordable mutation (mirrors the history
+            // capture conditions). Computed independently of `this.history` so the
+            // op-log records even when history is disabled.
+            let recorded = false;
+            if (isMutating && flowId) {
                 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);
-                    }
+                    recorded = ops.some((o) => o['op'] !== 'select_nodes' && o['op'] !== 'select_edges' && o['op'] !== 'deselect_all');
                 }
                 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);
-                    }
+                    recorded = Object.keys(positions).length > 0;
                 }
                 else {
+                    recorded = true;
+                }
+            }
+            if (recorded && flowId) {
+                if (this.history && snapshot) {
                     this.history.capture(flowId, snapshot);
-                    this.emitHistory(flowId);
+                    this.emitHistory(flowId, source);
                 }
+                this.recordOp(flowId, req.method, params, source);
+            }
+            // Template-registry mutations are op-logged (for get_changes_since
+            // visibility) but not history-snapshotted.
+            if (isTemplateMutation && flowId) {
+                this.recordOp(flowId, req.method, params, source);
             }
             return { id: req.id, result: result ?? null };
         }
@@ -260,6 +313,9 @@ export class AngflowAgentBridge {
                     },
                 };
             }
+            if (err instanceof MutationDeniedError) {
+                return { id: req.id, error: { code: ERROR_MUTATION_DENIED, message: err.message } };
+            }
             // 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.
@@ -280,11 +336,26 @@ export class AngflowAgentBridge {
         }
         return null;
     }
-    emitHistory(flowId) {
+    emitHistory(flowId, source) {
         if (!this.history)
             return;
         const status = this.history.status(flowId);
-        this.emit({ event: 'flow.history', params: { flowId, ...status } });
+        this.emit({ event: 'flow.history', params: { flowId, ...status, ...(source ? { source } : {}) } });
+    }
+    recordOp(flowId, method, params, source) {
+        if (!this.opLog)
+            return;
+        // Shallow-clone params so a later in-place mutation of the caller's object
+        // can't corrupt a stored (replay-able) log entry.
+        const entry = this.opLog.append(flowId, { method, params: { ...params }, source });
+        if (this.onOp) {
+            try {
+                this.onOp(entry);
+            }
+            catch (err) {
+                this.reportError(err, { kind: 'dispatch', method });
+            }
+        }
     }
     emit(evt) {
         for (const t of this.transports) {
@@ -401,11 +472,59 @@ export class AngflowAgentBridge {
     }
     installHandlers() {
         this.handlers.set('list_flows', () => Array.from(this.flows.keys()));
-        this.handlers.set('get_state', (flow) => ({
-            nodes: flow.getNodes(),
-            edges: flow.getEdges(),
-            viewport: flow.getViewport(),
-        }));
+        this.handlers.set('get_state', (flow, params) => {
+            const hasGroup = params['groupId'] !== undefined;
+            const hasBounds = params['bounds'] !== undefined;
+            if (hasGroup && hasBounds) {
+                throw new InvalidParamsError('Pass either "groupId" or "bounds", not both.');
+            }
+            const allNodes = flow.getNodes();
+            const allEdges = flow.getEdges();
+            let nodes = allNodes;
+            let edges = allEdges;
+            if (hasGroup) {
+                const groupId = requireString(params, 'groupId');
+                if (!flow.getNode(groupId)) {
+                    throw new InvalidParamsError(`get_state: no node with id "${groupId}".`);
+                }
+                const ids = descendantIdsOf(groupId, buildChildMap(allNodes));
+                nodes = allNodes.filter((n) => ids.has(n.id));
+                edges = inducedEdges(allEdges, ids);
+            }
+            else if (hasBounds) {
+                const rect = requireRect(params, 'bounds');
+                nodes = allNodes.filter((n) => flow.isNodeIntersecting(n, rect, true));
+                const idSet = new Set(nodes.map((n) => n.id));
+                edges = inducedEdges(allEdges, idSet);
+            }
+            return {
+                nodes,
+                edges,
+                viewport: flow.getViewport(),
+                collapsedHiddenIds: flow.getCollapsedHiddenIds(),
+            };
+        });
+        this.handlers.set('get_summary', (flow) => {
+            const nodes = flow.getNodes();
+            const edges = flow.getEdges();
+            const childMap = buildChildMap(nodes);
+            const groups = nodes
+                .filter((n) => n.type === 'group')
+                .map((g) => ({
+                id: g.id,
+                label: nodeTitle(g),
+                collapsed: g.collapsed === true,
+                memberCount: descendantIdsOf(g.id, childMap).size,
+            }));
+            return {
+                counts: { nodes: nodes.length, edges: edges.length, groups: groups.length },
+                groups,
+                titles: nodes.map((n) => ({ id: n.id, type: n.type ?? 'default', label: nodeTitle(n) })),
+                viewport: flow.getViewport(),
+                bounds: nodes.length > 0 ? flow.getNodesBounds(nodes) : null,
+                collapsedHiddenIds: flow.getCollapsedHiddenIds(),
+            };
+        });
         this.handlers.set('get_nodes', (flow) => flow.getNodes());
         this.handlers.set('get_edges', (flow) => flow.getEdges());
         this.handlers.set('get_node', (flow, params) => {
@@ -417,10 +536,79 @@ export class AngflowAgentBridge {
             return flow.getEdge(id) ?? null;
         });
         this.handlers.set('add_node', (flow, params) => {
-            const node = validateNodeShape(requireObject(params, 'node'), 'add_node');
+            // Shallow-clone so we never mutate the caller's params object when minting.
+            const raw = { ...requireObject(params, 'node') };
+            if (raw['id'] == null || raw['id'] === '') {
+                raw['id'] = this.mintId(flow, 'node');
+            }
+            const node = validateNodeShape(raw, 'add_node');
             flow.addNodes(node);
             return flow.getNode(node.id) ?? null;
         });
+        this.handlers.set('group_nodes', async (flow, params) => {
+            const nodeIds = optionalStringArray(params, 'nodeIds');
+            if (!nodeIds || nodeIds.length === 0) {
+                throw new InvalidParamsError('Param "nodeIds" must be a non-empty array of strings.');
+            }
+            for (const id of nodeIds) {
+                if (!flow.getNode(id))
+                    throw new InvalidParamsError(`group_nodes: unknown node id "${id}".`);
+            }
+            const suppliedGroupId = typeof params['groupId'] === 'string' && params['groupId'] ? params['groupId'] : undefined;
+            if (suppliedGroupId && flow.getNode(suppliedGroupId)) {
+                throw new InvalidParamsError(`group_nodes: a node with id "${suppliedGroupId}" already exists.`);
+            }
+            const groupId = suppliedGroupId ?? this.mintId(flow, 'group');
+            const label = typeof params['label'] === 'string' ? params['label'] : undefined;
+            const collapsed = typeof params['collapsed'] === 'boolean' ? params['collapsed'] : undefined;
+            // padding/headerHeight: inline typeof (not optionalPositiveNumber) — 0 is a valid inset.
+            const padding = typeof params['padding'] === 'number' ? params['padding'] : undefined;
+            const headerHeight = typeof params['headerHeight'] === 'number' ? params['headerHeight'] : undefined;
+            await flow.groupNodes(nodeIds, { groupId, label, collapsed, padding, headerHeight });
+            return { groupId };
+        });
+        this.handlers.set('set_node_group', async (flow, params) => {
+            const nodeId = requireString(params, 'nodeId');
+            if (!flow.getNode(nodeId))
+                throw new InvalidParamsError(`set_node_group: unknown node id "${nodeId}".`);
+            const rawGroup = params['groupId'];
+            if (rawGroup !== null && typeof rawGroup !== 'string') {
+                throw new InvalidParamsError('Param "groupId" must be a string or null.');
+            }
+            const groupId = rawGroup;
+            if (groupId !== null) {
+                if (!flow.getNode(groupId))
+                    throw new InvalidParamsError(`set_node_group: unknown group id "${groupId}".`);
+                if (groupId === nodeId || descendantIdsOf(nodeId, buildChildMap(flow.getNodes())).has(groupId)) {
+                    throw new InvalidParamsError('set_node_group: groupId would create a cycle (it is the node or a descendant).');
+                }
+            }
+            await flow.setNodeGroup(nodeId, groupId);
+            return { nodeId, groupId };
+        });
+        this.handlers.set('set_group_collapsed', (flow, params) => {
+            const groupId = requireString(params, 'groupId');
+            if (!flow.getNode(groupId))
+                throw new InvalidParamsError(`set_group_collapsed: unknown group id "${groupId}".`);
+            const collapsed = params['collapsed'];
+            if (typeof collapsed !== 'boolean')
+                throw new InvalidParamsError('Param "collapsed" must be a boolean.');
+            flow.setNodeCollapsed(groupId, collapsed);
+            return { groupId, collapsed };
+        });
+        this.handlers.set('dissolve_group', async (flow, params) => {
+            const groupId = requireString(params, 'groupId');
+            if (!flow.getNode(groupId))
+                throw new InvalidParamsError(`dissolve_group: unknown group id "${groupId}".`);
+            const memberIds = await flow.dissolveGroup(groupId);
+            return { dissolvedGroupId: groupId, memberIds };
+        });
+        this.handlers.set('get_group_bounds', (flow, params) => {
+            const groupId = requireString(params, 'groupId');
+            if (!flow.getNode(groupId))
+                return null;
+            return flow.getGroupBox(groupId);
+        });
         this.handlers.set('add_edge', (flow, params) => {
             const edge = validateEdgeShape(requireObject(params, 'edge'), 'add_edge');
             flow.addEdges(edge);
@@ -429,12 +617,14 @@ export class AngflowAgentBridge {
         this.handlers.set('update_node', (flow, params) => {
             const id = requireString(params, 'id');
             const patch = requireObject(params, 'patch');
+            validateStylePatch(patch, 'update_node/patch', 'node');
             flow.updateNode(id, patch);
             return flow.getNode(id) ?? null;
         });
         this.handlers.set('update_edge', (flow, params) => {
             const id = requireString(params, 'id');
             const patch = requireObject(params, 'patch');
+            validateStylePatch(patch, 'update_edge/patch', 'edge');
             flow.updateEdge(id, patch);
             return flow.getEdge(id) ?? null;
         });
@@ -461,6 +651,7 @@ export class AngflowAgentBridge {
         this.handlers.set('fit_view', (flow, params) => {
             const padding = typeof params['padding'] === 'number' ? params['padding'] : undefined;
             const duration = typeof params['duration'] === 'number' ? params['duration'] : undefined;
+            const minZoom = optionalPositiveNumber(params, 'minZoom');
             const nodeIds = optionalStringArray(params, 'nodeIds');
             const nodes = nodeIds
                 ? nodeIds
@@ -468,7 +659,7 @@ export class AngflowAgentBridge {
                     .filter((n) => !!n)
                     .map((n) => ({ id: n.id }))
                 : undefined;
-            return flow.fitView({ padding, duration, nodes });
+            return flow.fitView({ padding, duration, minZoom, nodes });
         });
         this.handlers.set('set_viewport', (flow, params) => {
             const viewport = requireObject(params, 'viewport');
@@ -590,7 +781,8 @@ export class AngflowAgentBridge {
             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 });
+            const minZoom = optionalPositiveNumber(params, 'minZoom');
+            return flow.fitBounds(bounds, { padding, duration, minZoom });
         });
         this.handlers.set('add_nodes', (flow, params) => {
             const nodes = requireArray(params, 'nodes').map((n, i) => validateNodeShape(n, `add_nodes[${i}]`));
@@ -635,6 +827,23 @@ export class AngflowAgentBridge {
         });
         this.handlers.set('apply_changes', (flow, params) => {
             const ops = requireArray(params, 'ops');
+            // Cap the AGGREGATE element count across all ops. Each add_nodes/add_edges
+            // op is already capped at MAX_BULK_ELEMENTS, but nothing bounded the
+            // product — 5000 add_nodes ops of 5000 nodes each would request ~25M
+            // inserts in one synchronous batch (main-thread freeze / OOM).
+            let requestedElements = 0;
+            for (const o of ops) {
+                const op = o['op'];
+                if (op === 'add_node' || op === 'add_edge')
+                    requestedElements += 1;
+                else if (op === 'add_nodes')
+                    requestedElements += Array.isArray(o['nodes']) ? o['nodes'].length : 0;
+                else if (op === 'add_edges')
+                    requestedElements += Array.isArray(o['edges']) ? o['edges'].length : 0;
+            }
+            if (requestedElements > MAX_BULK_ELEMENTS) {
+                throw new InvalidParamsError(`apply_changes: the batch requests ${requestedElements} elements, exceeding the maximum of ${MAX_BULK_ELEMENTS} across all 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-
@@ -743,6 +952,13 @@ export class AngflowAgentBridge {
             this.history.clear(flowId);
             this.emitHistory(flowId);
         });
+        this.handlers.set('get_changes_since', (flow, params) => {
+            const flowId = this.findFlowId(flow);
+            if (!this.opLog || !flowId)
+                return { ops: [], cursor: 0, truncated: false };
+            const since = typeof params['since'] === 'number' ? params['since'] : 0;
+            return this.opLog.since(flowId, since);
+        });
         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) => {
@@ -779,6 +995,7 @@ export class AngflowAgentBridge {
             }
             const nodeSep = typeof params['nodeSep'] === 'number' ? params['nodeSep'] : undefined;
             const rankSep = typeof params['rankSep'] === 'number' ? params['rankSep'] : undefined;
+            const minZoom = optionalPositiveNumber(params, 'minZoom');
             const nodeIds = optionalStringArray(params, 'nodeIds');
             if (nodeIds) {
                 for (const id of nodeIds) {
@@ -855,9 +1072,10 @@ export class AngflowAgentBridge {
             // position, keeping grouped children inside their group.
             await flow.setNodePositions(actuallyApplied, { coordinateSpace: 'absolute' });
             const shouldFit = params['fitView'] !== false;
+            let fit = null;
             if (shouldFit && Object.keys(actuallyApplied).length > 0) {
                 try {
-                    await flow.fitView({});
+                    fit = await flow.fitView({ minZoom });
                 }
                 catch (err) {
                     // Best-effort viewport fit: never fail the tool over a cosmetic step,
@@ -865,10 +1083,10 @@ export class AngflowAgentBridge {
                     this.reportError(err, { kind: 'dispatch', method: 'layout_nodes' });
                 }
             }
-            return { positions: actuallyApplied };
+            return { positions: actuallyApplied, fit };
         });
     }
-    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.ɵ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 }, { token: AGENT_CAN_MUTATE, optional: true }, { token: AGENT_ON_OP, optional: true }, { token: AGENT_OPLOG_OPTIONS, 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.15", ngImport: i0, type: AngflowAgentBridge, decorators: [{
@@ -894,6 +1112,21 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.15", ngImpo
                 }, {
                     type: Inject,
                     args: [AGENT_LAYOUT]
+                }] }, { type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [AGENT_CAN_MUTATE]
+                }] }, { type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [AGENT_ON_OP]
+                }] }, { type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [AGENT_OPLOG_OPTIONS]
                 }] }] });
 class FlowNotFoundError extends Error {
 }
@@ -902,6 +1135,8 @@ class InvalidParamsError extends Error {
 /** Tool exists in the catalog but the deployment lacks a required capability. Maps to -32601. */
 class MethodUnavailableError extends Error {
 }
+class MutationDeniedError extends Error {
+}
 class ApplyChangesError extends Error {
     constructor(failedIndex, message) {
         super(message);
@@ -995,6 +1230,7 @@ function executeOp(flow, op) {
                 throw new InvalidParamsError('update_node: "patch" must be an object.');
             if (!flow.getNode(id))
                 throw new InvalidParamsError(`update_node: node "${id}" not found.`);
+            validateStylePatch(patch, 'apply_changes/update_node', 'node');
             flow.updateNode(id, patch);
             return flow.getNode(id) ?? null;
         }
@@ -1019,6 +1255,7 @@ function executeOp(flow, op) {
                 throw new InvalidParamsError('update_edge: "patch" must be an object.');
             if (!flow.getEdge(id))
                 throw new InvalidParamsError(`update_edge: edge "${id}" not found.`);
+            validateStylePatch(patch, 'apply_changes/update_edge', 'edge');
             flow.updateEdge(id, patch);
             return flow.getEdge(id) ?? null;
         }
@@ -1113,6 +1350,75 @@ function optionalStringArray(params, key) {
     }
     return value;
 }
+function optionalPositiveNumber(params, key) {
+    const value = params[key];
+    if (value == null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new InvalidParamsError(`Param "${key}" must be a finite number greater than 0.`);
+    }
+    return value;
+}
+function requireRect(params, key) {
+    const v = requireObject(params, key);
+    for (const k of ['x', 'y', 'width', 'height']) {
+        if (typeof v[k] !== 'number' || !Number.isFinite(v[k])) {
+            throw new InvalidParamsError(`Param "${key}.${k}" must be a finite number.`);
+        }
+    }
+    return v;
+}
+/** Build a parentId → child-ids map from a node list in one pass. */
+function buildChildMap(nodes) {
+    const map = new Map();
+    for (const n of nodes) {
+        if (n.parentId != null) {
+            const arr = map.get(n.parentId);
+            if (arr)
+                arr.push(n.id);
+            else
+                map.set(n.parentId, [n.id]);
+        }
+    }
+    return map;
+}
+/**
+ * Nesting-aware descendant ids of a node (excludes the node itself; cycle-guarded).
+ * Takes a prebuilt child map so callers that resolve many groups (e.g. get_summary)
+ * build it once rather than per group.
+ */
+function descendantIdsOf(groupId, childrenByParent) {
+    const out = new Set();
+    // BFS with an index pointer rather than queue.shift() (which is O(n) per
+    // dequeue) — keeps this O(n) for deep hierarchies up to the bulk cap.
+    const queue = [...(childrenByParent.get(groupId) ?? [])];
+    for (let head = 0; head < queue.length; head++) {
+        const id = queue[head];
+        if (out.has(id))
+            continue; // self-parent / cycle guard
+        out.add(id);
+        const kids = childrenByParent.get(id);
+        if (kids)
+            queue.push(...kids);
+    }
+    return out;
+}
+/** Edges whose source AND target are both in the id set. */
+function inducedEdges(edges, nodeIds) {
+    return edges.filter((e) => nodeIds.has(e.source) && nodeIds.has(e.target));
+}
+/** Best-effort display title for a node: data.label/title/name, else type, else id. */
+function nodeTitle(node) {
+    const data = node.data;
+    for (const key of ['label', 'title', 'name']) {
+        const v = data?.[key];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    if (typeof node.type === 'string' && node.type.length > 0)
+        return node.type;
+    return node.id;
+}
 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']);
@@ -1199,8 +1505,12 @@ function validateTemplateSpec(value, ctx) {
  * engines (`expression(`). Angular's style sanitization already blocks
  * script execution, so this is a narrow redressing/beaconing guard rather
  * than a full CSS allowlist.
+ *
+ * The backslash clause defeats CSS unicode-escape obfuscation — e.g. `\75 rl(…)`
+ * decodes to `url(…)` in the browser and would otherwise slip past a plain
+ * substring match. Legitimate inline node/edge styles never need a backslash.
  */
-const CSS_VALUE_BLOCKLIST = /url\s*\(|expression\s*\(/i;
+const CSS_VALUE_BLOCKLIST = /url\s*\(|expression\s*\(|\\/i;
 /** Shared style/className validation for agent-supplied nodes and edges. */
 function validateStyleAndClassName(o, ctx, kind) {
     const style = o['style'];
@@ -1209,11 +1519,17 @@ function validateStyleAndClassName(o, ctx, kind) {
             throw new InvalidParamsError(`${ctx}: ${kind}.style must be a plain object of CSS property/value pairs.`);
         }
         for (const [prop, raw] of Object.entries(style)) {
+            // Validate the KEY too: edge styles are rendered via raw `[attr.style]`
+            // string concatenation, so a key like "x: url(...); y" would smuggle a
+            // remote-fetch declaration past a value-only check.
+            if (/[:;\\]|url\s*\(|expression\s*\(/i.test(prop)) {
+                throw new InvalidParamsError(`${ctx}: ${kind}.style property name "${prop}" is invalid (must be a plain CSS property).`);
+            }
             if (typeof raw !== 'string' && typeof raw !== 'number') {
                 throw new InvalidParamsError(`${ctx}: ${kind}.style["${prop}"] must be a string or number.`);
             }
             if (typeof raw === 'string' && CSS_VALUE_BLOCKLIST.test(raw)) {
-                throw new InvalidParamsError(`${ctx}: ${kind}.style["${prop}"] must not contain "url(" or "expression(".`);
+                throw new InvalidParamsError(`${ctx}: ${kind}.style["${prop}"] must not contain "url(", "expression(", or a "\\" escape.`);
             }
         }
     }
@@ -1221,6 +1537,20 @@ function validateStyleAndClassName(o, ctx, kind) {
         throw new InvalidParamsError(`${ctx}: ${kind}.className must be a string.`);
     }
 }
+/**
+ * Validate the style/className on a mutation patch (update_node / update_edge /
+ * apply_changes update ops). Unlike validateNodeShape/validateEdgeShape this
+ * runs on partial patches, so agent-supplied styles on the update paths get the
+ * same url()/expression()/key guard as the add paths.
+ */
+function validateStylePatch(patch, ctx, kind) {
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch))
+        return;
+    const p = patch;
+    if ('style' in p || 'className' in p) {
+        validateStyleAndClassName(p, ctx, kind);
+    }
+}
 /** Validate that `value` is a structurally valid Node payload for add_*. */
 function validateNodeShape(value, ctx) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {