@auto-engineer/pipeline 0.0.1 → 0.15.0

package/dist/src/server/pipeline-server.specs.js

@@ -104,44 +104,392 @@ describe('PipelineServer', () => {
             expect(data.nodes.some((n) => n.id === 'evt:Start')).toBe(true);
             await server.stop();
         });
-        it('should return pipeline response with commandToEvents', async () => {
+        it('should use displayName as label for command graph nodes', async () => {
             const handler = {
-                name: 'Gen',
-                events: ['GenDone', 'GenProgress'],
-                handle: async () => ({ type: 'GenDone', data: {} }),
+                name: 'Cmd',
+                displayName: 'My Command',
+                handle: async () => ({ type: 'Done', data: {} }),
+            };
+            const pipeline = define('test').on('Start').emit('Cmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:Cmd');
+            expect(cmdNode?.label).toBe('My Command');
+            await server.stop();
+        });
+        it('should use command name as graph node label when displayName not provided', async () => {
+            const handler = {
+                name: 'SimpleCmd',
+                handle: async () => ({ type: 'Done', data: {} }),
             };
+            const pipeline = define('test').on('Start').emit('SimpleCmd', {}).build();
             const server = new PipelineServer({ port: 0 });
             server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
             await server.start();
             const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
-            expect(data.commandToEvents).toEqual({ Gen: ['GenDone', 'GenProgress'] });
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:SimpleCmd');
+            expect(cmdNode?.label).toBe('SimpleCmd');
             await server.stop();
         });
-        it('should return pipeline response with eventToCommand', async () => {
+        it('should filter out event nodes when excludeTypes=event', async () => {
+            const pipeline = define('test').on('Start').emit('Cmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?excludeTypes=event`);
+            expect(data.nodes.every((n) => n.type !== 'event')).toBe(true);
+            await server.stop();
+        });
+        it('should reconnect edges when maintainEdges=true and filter commands', async () => {
             const pipeline = define('test').on('Start').emit('Process', {}).build();
             const server = new PipelineServer({ port: 0 });
             server.registerPipeline(pipeline);
             await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?excludeTypes=command&maintainEdges=true`);
+            expect(data.nodes.every((n) => n.type !== 'command')).toBe(true);
+            expect(data.edges).toHaveLength(0);
+            await server.stop();
+        });
+        it('should filter multiple node types', async () => {
+            const pipeline = define('test')
+                .on('Start')
+                .emit('CheckA', {})
+                .emit('CheckB', {})
+                .settled(['CheckA', 'CheckB'])
+                .dispatch({ dispatches: [] }, () => { })
+                .build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?excludeTypes=event,settled`);
+            expect(data.nodes.every((n) => n.type !== 'event' && n.type !== 'settled')).toBe(true);
+            await server.stop();
+        });
+        it('should reconnect commands through events when filtering events with maintainEdges=true', async () => {
+            const generateHandler = {
+                name: 'Generate',
+                events: ['Generated'],
+                handle: async () => ({ type: 'Generated', data: {} }),
+            };
+            const pipeline = define('test').on('Start').emit('Generate', {}).on('Generated').emit('Process', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([generateHandler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?excludeTypes=event&maintainEdges=true`);
+            expect(data.nodes.every((n) => n.type !== 'event')).toBe(true);
+            expect(data.edges.some((e) => e.from === 'cmd:Generate' && e.to === 'cmd:Process')).toBe(true);
+            await server.stop();
+        });
+        it('should have status idle on command nodes by default', async () => {
+            const handler = {
+                name: 'Cmd',
+                events: ['Done'],
+                handle: async () => ({ type: 'Done', data: {} }),
+            };
+            const pipeline = define('test').on('Start').emit('Cmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
             const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
-            expect(data.eventToCommand).toEqual({ Start: 'Process' });
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:Cmd');
+            expect(cmdNode?.status).toBe('idle');
             await server.stop();
         });
-        it('should return pipeline nodes with name, title, and status', async () => {
+        it('should not have status on event nodes', async () => {
             const handler = {
                 name: 'Cmd',
-                alias: 'cmd',
-                description: 'Test command',
+                events: ['Done'],
                 handle: async () => ({ type: 'Done', data: {} }),
             };
+            const pipeline = define('test').on('Start').emit('Cmd', {}).build();
             const server = new PipelineServer({ port: 0 });
             server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
             await server.start();
             const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
-            const cmdNode = data.nodes.find((n) => n.id === 'Cmd');
-            expect(cmdNode).toBeDefined();
-            expect(cmdNode?.name).toBe('Cmd');
-            expect(cmdNode?.title).toBe('Test command');
-            expect(cmdNode?.status).toBe('None');
+            const eventNode = data.nodes.find((n) => n.id === 'evt:Start');
+            expect(eventNode?.status).toBeUndefined();
+            await server.stop();
+        });
+        it('should have idle status on settled nodes when no correlationId provided', async () => {
+            const handler = {
+                name: 'CheckTests',
+                events: ['TestsPassed'],
+                handle: async () => ({ type: 'TestsPassed', data: {} }),
+            };
+            const pipeline = define('test')
+                .on('Start')
+                .emit('CheckTests', {})
+                .settled(['CheckTests'])
+                .dispatch({ dispatches: [] }, () => { })
+                .build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
+            const settledNode = data.nodes.find((n) => n.id === 'settled:CheckTests');
+            expect(settledNode?.status).toBe('idle');
+            expect(settledNode?.pendingCount).toBe(0);
+            expect(settledNode?.endedCount).toBe(0);
+            await server.stop();
+        });
+        it('should show running status for command being executed', async () => {
+            let resolveHandler = () => { };
+            const handlerPromise = new Promise((resolve) => {
+                resolveHandler = resolve;
+            });
+            const handler = {
+                name: 'SlowCmd',
+                events: ['Done'],
+                handle: async () => {
+                    await handlerPromise;
+                    return { type: 'Done', data: {} };
+                },
+            };
+            const pipeline = define('test').on('Start').emit('SlowCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'SlowCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 50));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${commandResponse.correlationId}`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:SlowCmd');
+            expect(cmdNode?.status).toBe('running');
+            resolveHandler();
+            await server.stop();
+        });
+        it('should show success status after command completes with success event', async () => {
+            const handler = {
+                name: 'SuccessCmd',
+                events: ['CmdCompleted'],
+                handle: async () => ({ type: 'CmdCompleted', data: {} }),
+            };
+            const pipeline = define('test').on('Start').emit('SuccessCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'SuccessCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${commandResponse.correlationId}`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:SuccessCmd');
+            expect(cmdNode?.status).toBe('success');
+            await server.stop();
+        });
+        it('should show error status after command completes with failed event', async () => {
+            const handler = {
+                name: 'FailCmd',
+                events: ['CmdFailed'],
+                handle: async () => ({ type: 'CmdFailed', data: { error: 'Something went wrong' } }),
+            };
+            const pipeline = define('test').on('Start').emit('FailCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'FailCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${commandResponse.correlationId}`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:FailCmd');
+            expect(cmdNode?.status).toBe('error');
+            await server.stop();
+        });
+        it('should broadcast PipelineRunStarted event when new correlationId is first seen', async () => {
+            const handler = {
+                name: 'StartCmd',
+                events: ['Started'],
+                handle: async () => ({ type: 'Started', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('StartCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'StartCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const msgs = await fetchAs(`http://localhost:${server.port}/messages`);
+            const pipelineRunStarted = msgs.find((m) => m.message.type === 'PipelineRunStarted');
+            expect(pipelineRunStarted).toBeDefined();
+            expect((pipelineRunStarted?.message).correlationId).toBe(commandResponse.correlationId);
+            expect((pipelineRunStarted?.message).data?.triggerCommand).toBe('StartCmd');
+            await server.stop();
+        });
+        it('should broadcast NodeStatusChanged event when command starts running', async () => {
+            const handler = {
+                name: 'RunCmd',
+                events: ['RunDone'],
+                handle: async () => ({ type: 'RunDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('RunCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'RunCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const msgs = await fetchAs(`http://localhost:${server.port}/messages`);
+            const nodeStatusChanged = msgs.filter((m) => m.message.type === 'NodeStatusChanged');
+            const runningEvent = nodeStatusChanged.find((m) => m.message.data?.status === 'running');
+            expect(runningEvent).toBeDefined();
+            expect((runningEvent?.message).data?.nodeId).toBe('cmd:RunCmd');
+            expect((runningEvent?.message).data?.previousStatus).toBe('idle');
+            expect((runningEvent?.message).correlationId).toBe(commandResponse.correlationId);
+            await server.stop();
+        });
+        it('should broadcast NodeStatusChanged event when command completes', async () => {
+            const handler = {
+                name: 'CompleteCmd',
+                events: ['CompleteDone'],
+                handle: async () => ({ type: 'CompleteDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('CompleteCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'CompleteCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const msgs = await fetchAs(`http://localhost:${server.port}/messages`);
+            const nodeStatusChanged = msgs.filter((m) => m.message.type === 'NodeStatusChanged');
+            const successEvent = nodeStatusChanged.find((m) => m.message.data?.status === 'success');
+            expect(successEvent).toBeDefined();
+            expect((successEvent?.message).data?.nodeId).toBe('cmd:CompleteCmd');
+            expect((successEvent?.message).data?.previousStatus).toBe('running');
+            expect((successEvent?.message).correlationId).toBe(commandResponse.correlationId);
+            await server.stop();
+        });
+        it('should persist status across multiple /pipeline calls', async () => {
+            const handler = {
+                name: 'PersistCmd',
+                events: ['PersistDone'],
+                handle: async () => ({ type: 'PersistDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('PersistCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'PersistCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const firstCall = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${commandResponse.correlationId}`);
+            expect(firstCall.nodes.find((n) => n.id === 'cmd:PersistCmd')?.status).toBe('success');
+            const secondCall = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${commandResponse.correlationId}`);
+            expect(secondCall.nodes.find((n) => n.id === 'cmd:PersistCmd')?.status).toBe('success');
+            await server.stop();
+        });
+        it('should track status independently for different correlationIds', async () => {
+            const handler = {
+                name: 'IndependentCmd',
+                events: ['IndependentDone'],
+                handle: async () => ({ type: 'IndependentDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('IndependentCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const run1 = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'IndependentCmd', data: {} }),
+            });
+            const run2 = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'IndependentCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            expect(run1.correlationId).not.toBe(run2.correlationId);
+            const pipeline1 = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${run1.correlationId}`);
+            const pipeline2 = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${run2.correlationId}`);
+            expect(pipeline1.nodes.find((n) => n.id === 'cmd:IndependentCmd')?.status).toBe('success');
+            expect(pipeline2.nodes.find((n) => n.id === 'cmd:IndependentCmd')?.status).toBe('success');
+            await server.stop();
+        });
+        it('should show idle status for all command nodes when no correlationId provided', async () => {
+            const handler = {
+                name: 'IdleCmd',
+                events: ['IdleDone'],
+                handle: async () => ({ type: 'IdleDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('IdleCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'IdleCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const pipelineWithoutCorrelation = await fetchAs(`http://localhost:${server.port}/pipeline`);
+            const cmdNode = pipelineWithoutCorrelation.nodes.find((n) => n.id === 'cmd:IdleCmd');
+            expect(cmdNode?.status).toBe('idle');
+            await server.stop();
+        });
+        it('should return latestRun with the most recent correlationId', async () => {
+            const handler = {
+                name: 'LatestCmd',
+                events: ['LatestDone'],
+                handle: async () => ({ type: 'LatestDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('LatestCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const run1 = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'LatestCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 50));
+            const run2 = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'LatestCmd', data: {} }),
+            });
+            await new Promise((r) => setTimeout(r, 50));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
+            expect(data.latestRun).toBe(run2.correlationId);
+            expect(data.latestRun).not.toBe(run1.correlationId);
             await server.stop();
         });
     });
@@ -216,15 +564,6 @@ describe('PipelineServer', () => {
             await server.stop();
         });
     });
-    describe('GET /sessions', () => {
-        it('should return sessions', async () => {
-            const server = new PipelineServer({ port: 0 });
-            await server.start();
-            const data = await fetchAs(`http://localhost:${server.port}/sessions`);
-            expect(Array.isArray(data)).toBe(true);
-            await server.stop();
-        });
-    });
     describe('event routing', () => {
         it('should route events through pipeline', async () => {
             const handler = {
@@ -284,6 +623,55 @@ describe('PipelineServer', () => {
             expect(mermaid).toContain('flowchart LR');
             await server.stop();
         });
+        it('should filter out event nodes when excludeTypes=event', async () => {
+            const pipeline = define('test').on('Start').emit('Process', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerPipeline(pipeline);
+            await server.start();
+            const res = await fetch(`http://localhost:${server.port}/pipeline/mermaid?excludeTypes=event`);
+            const mermaid = await res.text();
+            expect(mermaid).not.toContain('evt_Start');
+            expect(mermaid).toContain('Process[Process]');
+            await server.stop();
+        });
+        it('should filter out settled nodes when excludeTypes=settled', async () => {
+            const checkAHandler = {
+                name: 'CheckA',
+                events: ['CheckAPassed', 'CheckAFailed'],
+                handle: async () => ({ type: 'CheckAPassed', data: {} }),
+            };
+            const pipeline = define('test')
+                .on('Start')
+                .emit('CheckA', {})
+                .settled(['CheckA'])
+                .dispatch({ dispatches: [] }, () => { })
+                .build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([checkAHandler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const res = await fetch(`http://localhost:${server.port}/pipeline/mermaid?excludeTypes=settled`);
+            const mermaid = await res.text();
+            expect(mermaid).not.toContain('settled_');
+            expect(mermaid).toContain('CheckA');
+            await server.stop();
+        });
+        it('should use displayName as label for command nodes in mermaid diagram', async () => {
+            const handler = {
+                name: 'Cmd',
+                displayName: 'My Command',
+                handle: async () => ({ type: 'Done', data: {} }),
+            };
+            const pipeline = define('test').on('Start').emit('Cmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const res = await fetch(`http://localhost:${server.port}/pipeline/mermaid`);
+            const mermaid = await res.text();
+            expect(mermaid).toContain('Cmd[My Command]');
+            await server.stop();
+        });
         it('should include event nodes in mermaid diagram', async () => {
             const pipeline = define('test').on('Start').emit('Process', {}).build();
             const server = new PipelineServer({ port: 0 });
@@ -294,6 +682,26 @@ describe('PipelineServer', () => {
             expect(mermaid).toContain('evt_Start');
             await server.stop();
         });
+        it('should use displayName as label for event nodes in mermaid diagram', async () => {
+            const handler = {
+                name: 'Cmd',
+                events: [{ name: 'CmdCompleted', displayName: 'Command Completed' }],
+                handle: async () => ({ type: 'CmdCompleted', data: {} }),
+            };
+            const nextHandler = {
+                name: 'NextCmd',
+                handle: async () => ({ type: 'Done', data: {} }),
+            };
+            const pipeline = define('test').on('Start').emit('Cmd', {}).on('CmdCompleted').emit('NextCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler, nextHandler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const res = await fetch(`http://localhost:${server.port}/pipeline/mermaid`);
+            const mermaid = await res.text();
+            expect(mermaid).toContain('evt_CmdCompleted([Command Completed])');
+            await server.stop();
+        });
         it('should include command nodes in mermaid diagram', async () => {
             const pipeline = define('test').on('Start').emit('Process', {}).build();
             const server = new PipelineServer({ port: 0 });
@@ -468,7 +876,7 @@ describe('PipelineServer', () => {
             expect(mermaid).not.toContain('ServerStartFailed');
             await server.stop();
         });
-        it('should show edges from command events to settled node, not from commands', async () => {
+        it('should show edges from commands to settled node', async () => {
             const checkAHandler = {
                 name: 'CheckA',
                 events: ['CheckAPassed', 'CheckAFailed'],
@@ -492,12 +900,8 @@ describe('PipelineServer', () => {
             await server.start();
             const res = await fetch(`http://localhost:${server.port}/pipeline/mermaid`);
             const mermaid = await res.text();
-            expect(mermaid).toContain('evt_CheckAPassed --> settled_CheckA_CheckB');
-            expect(mermaid).toContain('evt_CheckAFailed --> settled_CheckA_CheckB');
-            expect(mermaid).toContain('evt_CheckBPassed --> settled_CheckA_CheckB');
-            expect(mermaid).toContain('evt_CheckBFailed --> settled_CheckA_CheckB');
-            expect(mermaid).not.toMatch(/CheckA --> settled_/);
-            expect(mermaid).not.toMatch(/CheckB --> settled_/);
+            expect(mermaid).toContain('CheckA --> settled_CheckA_CheckB');
+            expect(mermaid).toContain('CheckB --> settled_CheckA_CheckB');
             await server.stop();
         });
         it('should show edges from settled node to dispatched commands', async () => {
@@ -523,7 +927,7 @@ describe('PipelineServer', () => {
             await server.start();
             const res = await fetch(`http://localhost:${server.port}/pipeline/mermaid`);
             const mermaid = await res.text();
-            expect(mermaid).toContain('settled_CheckA --> RetryCommand');
+            expect(mermaid).toContain('settled_CheckA -.->|retry| RetryCommand');
             await server.stop();
         });
         it('should style backLink edges in red', async () => {
@@ -553,6 +957,57 @@ describe('PipelineServer', () => {
             expect(mermaid).toMatch(/stroke:#[a-fA-F0-9]{6}|stroke:red/);
             await server.stop();
         });
+        it('should mark event-to-command edges as backLink when they create cycles', async () => {
+            const generateHandler = {
+                name: 'GenerateIA',
+                events: ['IAGenerated', 'IAValidationFailed'],
+                handle: async () => ({ type: 'IAGenerated', data: {} }),
+            };
+            const pipeline = define('test')
+                .on('Start')
+                .emit('GenerateIA', {})
+                .on('IAValidationFailed')
+                .emit('GenerateIA', {})
+                .build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([generateHandler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
+            const backLinkEdge = data.edges.find((e) => e.from === 'evt:IAValidationFailed' && e.to === 'cmd:GenerateIA');
+            expect(backLinkEdge).toBeDefined();
+            expect(backLinkEdge?.backLink).toBe(true);
+            await server.stop();
+        });
+        it('should NOT mark forward edges as backLink when cycle is broken by settled dispatch', async () => {
+            const implHandler = {
+                name: 'ImplementSlice',
+                events: ['SliceImplemented'],
+                handle: async () => ({ type: 'SliceImplemented', data: {} }),
+            };
+            const checkHandler = {
+                name: 'CheckTests',
+                events: ['TestsCheckPassed', 'TestsCheckFailed'],
+                handle: async () => ({ type: 'TestsCheckPassed', data: {} }),
+            };
+            const pipeline = define('test')
+                .on('Start')
+                .emit('ImplementSlice', {})
+                .on('SliceImplemented')
+                .emit('CheckTests', {})
+                .settled(['CheckTests'])
+                .dispatch({ dispatches: ['ImplementSlice'] }, () => { })
+                .build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([implHandler, checkHandler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
+            const forwardEdge = data.edges.find((e) => e.from === 'evt:SliceImplemented' && e.to === 'cmd:CheckTests');
+            expect(forwardEdge).toBeDefined();
+            expect(forwardEdge?.backLink).toBeUndefined();
+            await server.stop();
+        });
         it('should add event nodes from settled handler commandToEvents when not already added', async () => {
             const checkAHandler = {
                 name: 'CheckA',
@@ -594,6 +1049,17 @@ describe('PipelineServer', () => {
             expect(res.headers.get('content-type')).toContain('text/html');
             await server.stop();
         });
+        it('should filter nodes when excludeTypes is provided', async () => {
+            const pipeline = define('test').on('Start').emit('Process', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerPipeline(pipeline);
+            await server.start();
+            const res = await fetch(`http://localhost:${server.port}/pipeline/diagram?excludeTypes=event`);
+            const html = await res.text();
+            expect(html).not.toContain('evt_Start');
+            expect(html).toContain('Process');
+            await server.stop();
+        });
         it('should include mermaid.js script', async () => {
             const pipeline = define('test').on('Start').emit('Process', {}).build();
             const server = new PipelineServer({ port: 0 });
@@ -628,6 +1094,285 @@ describe('PipelineServer', () => {
             await server.stop();
         });
     });
+    describe('item-level tracking', () => {
+        it('should extract itemKey from command data using registered extractor', async () => {
+            const handler = {
+                name: 'ImplementSlice',
+                events: ['SliceImplemented'],
+                handle: async () => ({ type: 'SliceImplemented', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('ImplementSlice', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            server.registerItemKeyExtractor('ImplementSlice', (d) => d.slicePath);
+            await server.start();
+            const commandResponse = await fetchAs(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'ImplementSlice', data: { slicePath: '/server/slice-1' } }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${commandResponse.correlationId}`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:ImplementSlice');
+            expect(cmdNode?.pendingCount).toBe(0);
+            expect(cmdNode?.endedCount).toBe(1);
+            await server.stop();
+        });
+        it('should count multiple parallel items correctly', async () => {
+            const handler = {
+                name: 'ImplementSlice',
+                events: ['SliceImplemented'],
+                handle: async () => ({ type: 'SliceImplemented', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('ImplementSlice', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            server.registerItemKeyExtractor('ImplementSlice', (d) => d.slicePath);
+            await server.start();
+            const correlationId = `corr-parallel-test`;
+            await Promise.all([
+                fetch(`http://localhost:${server.port}/command`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        type: 'ImplementSlice',
+                        data: { slicePath: '/server/slice-1' },
+                        correlationId,
+                    }),
+                }),
+                fetch(`http://localhost:${server.port}/command`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        type: 'ImplementSlice',
+                        data: { slicePath: '/server/slice-2' },
+                        correlationId,
+                    }),
+                }),
+                fetch(`http://localhost:${server.port}/command`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        type: 'ImplementSlice',
+                        data: { slicePath: '/server/slice-3' },
+                        correlationId,
+                    }),
+                }),
+            ]);
+            await new Promise((r) => setTimeout(r, 100));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${correlationId}`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:ImplementSlice');
+            expect(cmdNode?.pendingCount).toBe(0);
+            expect(cmdNode?.endedCount).toBe(3);
+            await server.stop();
+        });
+        it('should show pending count while commands are running', async () => {
+            const resolveHandlers = [];
+            const handler = {
+                name: 'SlowSlice',
+                events: ['SlowSliceDone'],
+                handle: async () => {
+                    await new Promise((resolve) => {
+                        resolveHandlers.push(resolve);
+                    });
+                    return { type: 'SlowSliceDone', data: {} };
+                },
+            };
+            const pipeline = define('test').on('Trigger').emit('SlowSlice', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            server.registerItemKeyExtractor('SlowSlice', (d) => d.id);
+            await server.start();
+            const correlationId = `corr-slow-test`;
+            void fetch(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'SlowSlice', data: { id: 'item-1' }, correlationId }),
+            });
+            void fetch(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'SlowSlice', data: { id: 'item-2' }, correlationId }),
+            });
+            void fetch(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'SlowSlice', data: { id: 'item-3' }, correlationId }),
+            });
+            await new Promise((r) => setTimeout(r, 50));
+            const midwayData = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${correlationId}`);
+            const midwayNode = midwayData.nodes.find((n) => n.id === 'cmd:SlowSlice');
+            expect(midwayNode?.pendingCount).toBe(3);
+            expect(midwayNode?.endedCount).toBe(0);
+            expect(midwayNode?.status).toBe('running');
+            resolveHandlers.forEach((r) => r());
+            await new Promise((r) => setTimeout(r, 50));
+            const finalData = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${correlationId}`);
+            const finalNode = finalData.nodes.find((n) => n.id === 'cmd:SlowSlice');
+            expect(finalNode?.pendingCount).toBe(0);
+            expect(finalNode?.endedCount).toBe(3);
+            expect(finalNode?.status).toBe('success');
+            await server.stop();
+        });
+        it('should show error status when any item fails', async () => {
+            const handler = {
+                name: 'MixedSlice',
+                events: ['MixedSliceDone', 'MixedSliceFailed'],
+                handle: async (cmd) => {
+                    if (cmd.data.shouldFail === true) {
+                        return { type: 'MixedSliceFailed', data: {} };
+                    }
+                    return { type: 'MixedSliceDone', data: {} };
+                },
+            };
+            const pipeline = define('test').on('Trigger').emit('MixedSlice', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            server.registerItemKeyExtractor('MixedSlice', (d) => d.id);
+            await server.start();
+            const correlationId = `corr-mixed-test`;
+            await Promise.all([
+                fetch(`http://localhost:${server.port}/command`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ type: 'MixedSlice', data: { id: 'pass-1' }, correlationId }),
+                }),
+                fetch(`http://localhost:${server.port}/command`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ type: 'MixedSlice', data: { id: 'fail-1', shouldFail: true }, correlationId }),
+                }),
+                fetch(`http://localhost:${server.port}/command`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ type: 'MixedSlice', data: { id: 'pass-2' }, correlationId }),
+                }),
+            ]);
+            await new Promise((r) => setTimeout(r, 100));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${correlationId}`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:MixedSlice');
+            expect(cmdNode?.pendingCount).toBe(0);
+            expect(cmdNode?.endedCount).toBe(3);
+            expect(cmdNode?.status).toBe('error');
+            await server.stop();
+        });
+        it('should reset item to running when retry command arrives for same itemKey', async () => {
+            let attemptCount = 0;
+            const handler = {
+                name: 'RetrySlice',
+                events: ['RetrySliceDone', 'RetrySliceFailed'],
+                handle: async () => {
+                    attemptCount++;
+                    if (attemptCount === 1) {
+                        return { type: 'RetrySliceFailed', data: {} };
+                    }
+                    return { type: 'RetrySliceDone', data: {} };
+                },
+            };
+            const pipeline = define('test').on('Trigger').emit('RetrySlice', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            server.registerItemKeyExtractor('RetrySlice', (d) => d.slicePath);
+            await server.start();
+            const correlationId = `corr-retry-test`;
+            const slicePath = '/server/retry-slice';
+            await fetch(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'RetrySlice', data: { slicePath }, correlationId }),
+            });
+            await new Promise((r) => setTimeout(r, 50));
+            const afterFailure = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${correlationId}`);
+            expect(afterFailure.nodes.find((n) => n.id === 'cmd:RetrySlice')?.status).toBe('error');
+            await fetch(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'RetrySlice', data: { slicePath }, correlationId }),
+            });
+            await new Promise((r) => setTimeout(r, 50));
+            const afterRetry = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${correlationId}`);
+            const node = afterRetry.nodes.find((n) => n.id === 'cmd:RetrySlice');
+            expect(node?.status).toBe('success');
+            expect(node?.pendingCount).toBe(0);
+            expect(node?.endedCount).toBe(1);
+            await server.stop();
+        });
+        it('should include pendingCount and endedCount in NodeStatusChanged events', async () => {
+            const handler = {
+                name: 'CountSlice',
+                events: ['CountSliceDone'],
+                handle: async () => ({ type: 'CountSliceDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('CountSlice', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            server.registerItemKeyExtractor('CountSlice', (d) => d.id);
+            await server.start();
+            const correlationId = `corr-counts-event-test`;
+            await fetch(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'CountSlice', data: { id: 'item-1' }, correlationId }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const msgs = await fetchAs(`http://localhost:${server.port}/messages`);
+            const nodeStatusChanged = msgs.filter((m) => m.message.type === 'NodeStatusChanged');
+            const successEvent = nodeStatusChanged.find((m) => m.message.data?.status === 'success');
+            expect(successEvent).toBeDefined();
+            expect((successEvent?.message).data?.pendingCount).toBe(0);
+            expect((successEvent?.message).data?.endedCount).toBe(1);
+            await server.stop();
+        });
+        it('should use requestId as fallback when no itemKey extractor is registered', async () => {
+            const handler = {
+                name: 'NoExtractorCmd',
+                events: ['NoExtractorDone'],
+                handle: async () => ({ type: 'NoExtractorDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('NoExtractorCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const correlationId = `corr-no-extractor-test`;
+            await fetch(`http://localhost:${server.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ type: 'NoExtractorCmd', data: {}, correlationId }),
+            });
+            await new Promise((r) => setTimeout(r, 100));
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline?correlationId=${correlationId}`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:NoExtractorCmd');
+            expect(cmdNode?.pendingCount).toBe(0);
+            expect(cmdNode?.endedCount).toBe(1);
+            expect(cmdNode?.status).toBe('success');
+            await server.stop();
+        });
+        it('should show idle status with zero counts when no correlationId provided', async () => {
+            const handler = {
+                name: 'IdleCountCmd',
+                events: ['IdleCountDone'],
+                handle: async () => ({ type: 'IdleCountDone', data: {} }),
+            };
+            const pipeline = define('test').on('Trigger').emit('IdleCountCmd', {}).build();
+            const server = new PipelineServer({ port: 0 });
+            server.registerCommandHandlers([handler]);
+            server.registerPipeline(pipeline);
+            await server.start();
+            const data = await fetchAs(`http://localhost:${server.port}/pipeline`);
+            const cmdNode = data.nodes.find((n) => n.id === 'cmd:IdleCountCmd');
+            expect(cmdNode?.status).toBe('idle');
+            expect(cmdNode?.pendingCount).toBe(0);
+            expect(cmdNode?.endedCount).toBe(0);
+            await server.stop();
+        });
+    });
     describe('integration', () => {
         it('should execute complete workflow', async () => {
             const handler = {