@auto-engineer/pipeline 1.82.0 → 1.83.0

package/ketchup-plan.md

@@ -918,6 +918,15 @@ it("should extract graph from emit handler", () => {
 
 ## DONE
 
+### Phase 13: PipelineRunCompleted Event (Bursts 107-112) ✅
+
+- [x] Burst 107: Create QuiescenceTracker class with increment/decrement/isQuiescent (f4bc85c4)
+- [x] Burst 108: Add debounce logic to QuiescenceTracker with configurable delay (411129cb)
+- [x] Burst 109-111: Wire QuiescenceTracker into PipelineServer, emit PipelineRunCompleted (0011d83b)
+- [x] Burst 112: Verify quiescence tracking handles retries naturally (bb928573)
+
+---
+
 ### Command Concurrency Control (Bursts CG-1 to CG-8) ✅
 
 - [x] Burst CG-1: Gate registration + passthrough (d0a733c8)

package/package.json

@@ -13,8 +13,8 @@
     "get-port": "^7.1.0",
     "jose": "^5.9.6",
     "nanoid": "^5.0.0",
-    "@auto-engineer/file-store": "1.82.0",
-    "@auto-engineer/message-bus": "1.82.0"
+    "@auto-engineer/file-store": "1.83.0",
+    "@auto-engineer/message-bus": "1.83.0"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",
@@ -23,7 +23,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.82.0",
+  "version": "1.83.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",

package/src/server/pipeline-server.specs.ts

@@ -2805,4 +2805,117 @@ describe('PipelineServer', () => {
       await server.stop();
     });
   });
+
+  describe('PipelineRunCompleted', () => {
+    it('emits PipelineRunCompleted after all commands complete and debounce passes', async () => {
+      const handler = {
+        name: 'DoWork',
+        events: ['WorkDone'],
+        handle: async () => ({ type: 'WorkDone', data: {} }),
+      };
+
+      const server = new PipelineServer({ port: 0 });
+      server.registerCommandHandlers([handler]);
+      await server.start();
+
+      await fetch(`http://localhost:${server.port}/command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ type: 'DoWork', data: {} }),
+      });
+
+      await new Promise((r) => setTimeout(r, 150));
+
+      const msgs = await fetchAs<StoredMessage[]>(`http://localhost:${server.port}/messages`);
+      expect(msgs.some((m) => m.message.type === 'PipelineRunCompleted')).toBe(true);
+
+      await server.stop();
+    });
+
+    it('does not emit PipelineRunCompleted while commands are still pending', async () => {
+      let resolveWork: (() => void) | undefined;
+      const handler = {
+        name: 'SlowWork',
+        events: ['SlowWorkDone'],
+        handle: async () => {
+          await new Promise<void>((r) => {
+            resolveWork = r;
+          });
+          return { type: 'SlowWorkDone', data: {} };
+        },
+      };
+
+      const server = new PipelineServer({ port: 0 });
+      server.registerCommandHandlers([handler]);
+      await server.start();
+
+      fetch(`http://localhost:${server.port}/command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ type: 'SlowWork', data: {} }),
+      });
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const msgsBeforeComplete = await fetchAs<StoredMessage[]>(`http://localhost:${server.port}/messages`);
+      expect(msgsBeforeComplete.some((m) => m.message.type === 'PipelineRunCompleted')).toBe(false);
+
+      if (resolveWork) resolveWork();
+      await new Promise((r) => setTimeout(r, 150));
+
+      const msgsAfterComplete = await fetchAs<StoredMessage[]>(`http://localhost:${server.port}/messages`);
+      expect(msgsAfterComplete.some((m) => m.message.type === 'PipelineRunCompleted')).toBe(true);
+
+      await server.stop();
+    });
+
+    it('does not emit PipelineRunCompleted while retry commands are dispatched', async () => {
+      let attemptCount = 0;
+      const checkHandler = {
+        name: 'CheckTests',
+        events: ['CheckTestsPassed', 'CheckTestsFailed'],
+        handle: async () => {
+          attemptCount++;
+          if (attemptCount < 3) {
+            return { type: 'CheckTestsFailed', data: { errors: 'fail' } };
+          }
+          return { type: 'CheckTestsPassed', data: {} };
+        },
+      };
+
+      const pipeline = define('retry-test')
+        .on('StartChecks')
+        .emit('CheckTests', () => ({}))
+        .settled(['CheckTests'])
+        .dispatch({ dispatches: ['CheckTests'] }, (events, send) => {
+          const failed = events.CheckTests?.some((e) => e.type === 'CheckTestsFailed');
+          if (failed && attemptCount < 3) {
+            send('CheckTests', {});
+            return { persist: true };
+          }
+        })
+        .build();
+
+      const server = new PipelineServer({ port: 0 });
+      server.registerCommandHandlers([checkHandler]);
+      server.registerPipeline(pipeline);
+      await server.start();
+
+      await fetch(`http://localhost:${server.port}/command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ type: 'CheckTests', data: {} }),
+      });
+
+      await new Promise((r) => setTimeout(r, 500));
+
+      const msgs = await fetchAs<StoredMessage[]>(`http://localhost:${server.port}/messages`);
+      const completedEvents = msgs.filter((m) => m.message.type === 'PipelineRunCompleted');
+
+      expect(completedEvents.length).toBe(1);
+      expect(attemptCount).toBe(3);
+
+      await server.stop();
+    });
+  });
 });

package/src/server/pipeline-server.ts

@@ -22,6 +22,7 @@ import { PipelineRuntime } from '../runtime/pipeline-runtime';
 import { createPipelineEventStore, type PipelineEventStoreContext } from '../store/pipeline-event-store';
 import { type ConcurrencyConfig, createCommandGate } from './command-gate';
 import { createPhasedBridge } from './phased-bridge';
+import { QuiescenceTracker } from './quiescence-tracker';
 import { SSEManager } from './sse-manager';
 import { createV2RuntimeBridge } from './v2-runtime-bridge';
 
@@ -70,6 +71,7 @@ export class PipelineServer {
   private readonly storeFileName?: string;
   private sqliteEventStore?: EventStore;
   private currentSessionId = '';
+  private readonly quiescenceTracker: QuiescenceTracker;
 
   constructor(config: PipelineServerConfig) {
     this.storeFileName = config.storeFileName;
@@ -97,6 +99,12 @@ export class PipelineServer {
     });
     this.sseManager = new SSEManager();
     this.commandGate = createCommandGate();
+    this.quiescenceTracker = new QuiescenceTracker({
+      debounceMs: 50,
+      onQuiescent: () => {
+        void this.emitPipelineRunCompleted();
+      },
+    });
   }
 
   get port(): number {
@@ -631,6 +639,29 @@ export class PipelineServer {
     ]);
   }
 
+  private async emitPipelineRunCompleted(): Promise<void> {
+    const correlationId = this.currentSessionId;
+    const requestId = `req-${nanoid()}`;
+    await this.eventStoreContext.eventStore.appendToStream(`pipeline-${correlationId}`, [
+      {
+        type: 'DomainEventEmitted',
+        data: {
+          correlationId,
+          requestId,
+          eventType: 'PipelineRunCompleted',
+          eventData: { correlationId, timestamp: new Date().toISOString() },
+          timestamp: new Date(),
+        },
+      },
+    ]);
+    const event: Event & { correlationId: string } = {
+      type: 'PipelineRunCompleted',
+      data: { correlationId, timestamp: new Date().toISOString() },
+      correlationId,
+    };
+    this.sseManager.broadcast(event);
+  }
+
   private async updateNodeStatus(
     correlationId: string,
     commandName: string,
@@ -1006,6 +1037,19 @@ export class PipelineServer {
     command: Command & { correlationId: string; requestId: string },
     handler: CommandHandlerWithMetadata,
     signal: AbortSignal,
+  ): Promise<void> {
+    this.quiescenceTracker.increment();
+    try {
+      await this.executeCommandInner(command, handler, signal);
+    } finally {
+      this.quiescenceTracker.decrement();
+    }
+  }
+
+  private async executeCommandInner(
+    command: Command & { correlationId: string; requestId: string },
+    handler: CommandHandlerWithMetadata,
+    signal: AbortSignal,
   ): Promise<void> {
     const itemKey = this.extractItemKey(command.type, command.data, command.requestId);
     await this.getOrCreateItemStatus(this.currentSessionId, command.type, itemKey, command.requestId);

package/src/server/quiescence-tracker.specs.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { QuiescenceTracker } from './quiescence-tracker';
+
+describe('QuiescenceTracker', () => {
+  describe('isQuiescent', () => {
+    it('returns true initially when no commands dispatched', () => {
+      const tracker = new QuiescenceTracker();
+
+      expect(tracker.isQuiescent()).toBe(true);
+    });
+
+    it('returns false after increment', () => {
+      const tracker = new QuiescenceTracker();
+
+      tracker.increment();
+
+      expect(tracker.isQuiescent()).toBe(false);
+    });
+
+    it('returns true after matching increment and decrement', () => {
+      const tracker = new QuiescenceTracker();
+      tracker.increment();
+
+      tracker.decrement();
+
+      expect(tracker.isQuiescent()).toBe(true);
+    });
+
+    it('returns false when multiple commands pending', () => {
+      const tracker = new QuiescenceTracker();
+
+      tracker.increment();
+      tracker.increment();
+      tracker.increment();
+      tracker.decrement();
+
+      expect(tracker.isQuiescent()).toBe(false);
+    });
+
+    it('returns true after all commands complete', () => {
+      const tracker = new QuiescenceTracker();
+      tracker.increment();
+      tracker.increment();
+      tracker.increment();
+
+      tracker.decrement();
+      tracker.decrement();
+      tracker.decrement();
+
+      expect(tracker.isQuiescent()).toBe(true);
+    });
+
+    it('remains quiescent after decrement when already at zero', () => {
+      const tracker = new QuiescenceTracker();
+
+      tracker.decrement();
+
+      expect(tracker.isQuiescent()).toBe(true);
+    });
+  });
+
+  describe('reset', () => {
+    it('restores quiescent state when commands were pending', () => {
+      const tracker = new QuiescenceTracker();
+      tracker.increment();
+      tracker.increment();
+
+      tracker.reset();
+
+      expect(tracker.isQuiescent()).toBe(true);
+    });
+  });
+
+  describe('onQuiescent callback with debounce', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('calls callback after debounce delay when quiescent', () => {
+      const callback = vi.fn();
+      const tracker = new QuiescenceTracker({ debounceMs: 100, onQuiescent: callback });
+      tracker.increment();
+
+      tracker.decrement();
+
+      expect(callback).not.toHaveBeenCalled();
+      vi.advanceTimersByTime(100);
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not call callback before debounce delay', () => {
+      const callback = vi.fn();
+      const tracker = new QuiescenceTracker({ debounceMs: 100, onQuiescent: callback });
+      tracker.increment();
+
+      tracker.decrement();
+      vi.advanceTimersByTime(50);
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('resets debounce timer when new command arrives during debounce', () => {
+      const callback = vi.fn();
+      const tracker = new QuiescenceTracker({ debounceMs: 100, onQuiescent: callback });
+      tracker.increment();
+      tracker.decrement();
+      vi.advanceTimersByTime(50);
+
+      tracker.increment();
+
+      vi.advanceTimersByTime(100);
+      expect(callback).not.toHaveBeenCalled();
+
+      tracker.decrement();
+      vi.advanceTimersByTime(100);
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not call callback when reset during debounce', () => {
+      const callback = vi.fn();
+      const tracker = new QuiescenceTracker({ debounceMs: 100, onQuiescent: callback });
+      tracker.increment();
+      tracker.decrement();
+      vi.advanceTimersByTime(50);
+
+      tracker.reset();
+
+      vi.advanceTimersByTime(100);
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('uses default debounce of 50ms when not specified', () => {
+      const callback = vi.fn();
+      const tracker = new QuiescenceTracker({ onQuiescent: callback });
+      tracker.increment();
+
+      tracker.decrement();
+
+      vi.advanceTimersByTime(49);
+      expect(callback).not.toHaveBeenCalled();
+      vi.advanceTimersByTime(1);
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/server/quiescence-tracker.ts

@@ -0,0 +1,57 @@
+export interface QuiescenceTrackerOptions {
+  debounceMs?: number;
+  onQuiescent?: () => void;
+}
+
+export class QuiescenceTracker {
+  private pendingCount = 0;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly debounceMs: number;
+  private readonly onQuiescent?: () => void;
+
+  constructor(options: QuiescenceTrackerOptions = {}) {
+    this.debounceMs = options.debounceMs ?? 50;
+    this.onQuiescent = options.onQuiescent;
+  }
+
+  increment(): void {
+    this.pendingCount++;
+    this.cancelDebounce();
+  }
+
+  decrement(): void {
+    if (this.pendingCount > 0) {
+      this.pendingCount--;
+    }
+    this.scheduleQuiescenceCheck();
+  }
+
+  isQuiescent(): boolean {
+    return this.pendingCount === 0;
+  }
+
+  reset(): void {
+    this.pendingCount = 0;
+    this.cancelDebounce();
+  }
+
+  private scheduleQuiescenceCheck(): void {
+    const callback = this.onQuiescent;
+    if (!this.isQuiescent() || !callback) {
+      return;
+    }
+    this.cancelDebounce();
+    this.debounceTimer = setTimeout(() => {
+      if (this.isQuiescent()) {
+        callback();
+      }
+    }, this.debounceMs);
+  }
+
+  private cancelDebounce(): void {
+    if (this.debounceTimer !== null) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+  }
+}