@angflow/angular 0.3.6 → 0.3.7

package/dist/esm/lib/agent/agent-bridge.service.d.ts

@@ -2,7 +2,8 @@ import { InjectionToken } from '@angular/core';
 import type { NgFlowService } from '../services/ng-flow.service';
 import type { AgentLayoutFn } from '../types/node-template';
 import type { AgentHistoryOptions } from './history';
-import type { AgentTransport } from './types';
+import type { OpLogEntry, OpLogOptions } from './op-log';
+import type { AgentTransport, AgentCanMutateFn } from './types';
 import * as i0 from "@angular/core";
 /** Provider token holding the user-supplied transport(s). */
 export declare const AGENT_TRANSPORTS: InjectionToken<AgentTransport[]>;
@@ -16,6 +17,12 @@ export declare const AGENT_ON_ERROR: InjectionToken<(err: unknown, ctx: {
 }) => void>;
 /** Optional host-provided layout function backing the `layout_nodes` tool. */
 export declare const AGENT_LAYOUT: InjectionToken<AgentLayoutFn>;
+/** Optional host write-guard for mutating tools. */
+export declare const AGENT_CAN_MUTATE: InjectionToken<AgentCanMutateFn>;
+/** Optional sink receiving each applied mutating op (for host persistence/replay). */
+export declare const AGENT_ON_OP: InjectionToken<(entry: OpLogEntry) => void>;
+/** Op-log config. `false` disables the op-log + get_changes_since. Default { maxOps: 1000 }. */
+export declare const AGENT_OPLOG_OPTIONS: InjectionToken<false | OpLogOptions>;
 /**
  * Routes JSON-RPC requests from one or more transports to registered
  * `NgFlowService` instances, and pushes change events back to the agent.
@@ -46,12 +53,16 @@ export declare class AngflowAgentBridge {
     private readonly flows;
     private readonly transports;
     private readonly history;
+    private readonly opLog;
+    private readonly onOp;
     private readonly handlers;
     private readonly injector;
     private readonly destroyRef;
     private readonly layoutFn;
+    private readonly canMutate;
     private started;
     private nextInProcessId;
+    private nextNodeIdSeq;
     private warnedOnBeforeDeleteBypass;
     /** Bumped every time a flow registers/unregisters. Useful for diagnostics. */
     readonly registeredFlows: import("@angular/core").WritableSignal<string[]>;
@@ -60,7 +71,7 @@ export declare class AngflowAgentBridge {
         kind: 'transport-start' | 'transport-send' | 'dispatch';
         transport?: AgentTransport;
         method?: string;
-    }) => void) | null, layoutFn: AgentLayoutFn | null);
+    }) => void) | null, layoutFn: AgentLayoutFn | null, canMutate: AgentCanMutateFn | null, onOp: ((entry: OpLogEntry) => void) | null, opLogOptions: OpLogOptions | false | null);
     private reportError;
     /**
      * Register a flow under `id`. The bridge subscribes to its `nodes`,
@@ -75,23 +86,28 @@ export declare class AngflowAgentBridge {
     unregister(id: string): void;
     /** Look up a registered flow. */
     getFlow(id: string): NgFlowService | undefined;
+    /** Mint a unique node/group id for a flow (collision-safe vs agent-supplied ids). */
+    private mintId;
     /**
      * 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.
      */
-    callTool(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    callTool(method: string, params?: Record<string, unknown>, opts?: {
+        source?: string;
+    }): Promise<unknown>;
     private start;
     /** Stop all transports. Invoked automatically when the owning injector is destroyed. */
     private stop;
     private dispatch;
     private findFlowId;
     private emitHistory;
+    private recordOp;
     private emit;
     private resolveFlow;
     private watchFlow;
     private installHandlers;
-    static ɵfac: i0.ɵɵFactoryDeclaration<AngflowAgentBridge, [{ optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AngflowAgentBridge, [{ optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AngflowAgentBridge>;
 }

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,6 +34,10 @@ 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.
 /** Max flow.state emission rate while any node drag is in progress. */
@@ -55,7 +67,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 +76,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 +86,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 +125,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 +140,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 +148,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 +227,24 @@ 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 source = req.source;
+            if (this.canMutate && isMutating) {
+                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 +257,29 @@ 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);
             }
             return { id: req.id, result: result ?? null };
         }
@@ -260,6 +303,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 +326,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 +462,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 +526,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);
@@ -461,6 +639,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 +647,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 +769,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}]`));
@@ -743,6 +923,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 +966,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 +1043,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 +1054,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 +1083,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 +1106,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);
@@ -1113,6 +1319,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']);