@outputai/core 0.5.1 → 0.5.2-next.17d8711.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.5.1",
+  "version": "0.5.2-next.17d8711.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/activity_integration/event_id_integration.spec.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { messageBus } from '#bus';
+import { emitEvent } from './events.js';
+
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+describe( 'eventId integration', () => {
+  beforeEach( () => {
+    messageBus.removeAllListeners();
+  } );
+
+  it( 'stamps a UUID v4 eventId on every emit (end-to-end via messageBus)', () => {
+    const handler = vi.fn();
+    messageBus.on( 'external:cost:llm:request', handler );
+
+    emitEvent( 'cost:llm:request', { modelId: 'gpt-4o' } );
+
+    expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
+      eventId: expect.stringMatching( UUID_V4_REGEX ),
+      modelId: 'gpt-4o'
+    } ) );
+  } );
+
+  it( 'cost:http:request and http:request for the same fetch get distinct eventIds', () => {
+    const costHandler = vi.fn();
+    const reqHandler = vi.fn();
+    messageBus.on( 'external:cost:http:request', costHandler );
+    messageBus.on( 'external:http:request', reqHandler );
+
+    const sharedRequestId = 'req-xyz';
+    emitEvent( 'cost:http:request', { requestId: sharedRequestId, url: 'https://x.test', cost: 1 } );
+    emitEvent( 'http:request', { requestId: sharedRequestId, url: 'https://x.test', status: 200 } );
+
+    const costEventId = costHandler.mock.calls[0][0].eventId;
+    const reqEventId = reqHandler.mock.calls[0][0].eventId;
+    expect( costEventId ).toMatch( UUID_V4_REGEX );
+    expect( reqEventId ).toMatch( UUID_V4_REGEX );
+    expect( costEventId ).not.toBe( reqEventId );
+  } );
+
+  it( 'honors a caller-supplied eventId end-to-end', () => {
+    const handler = vi.fn();
+    messageBus.on( 'external:custom:event', handler );
+
+    emitEvent( 'custom:event', { eventId: 'fixed-id-123', payload: 'hi' } );
+
+    expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
+      eventId: 'fixed-id-123',
+      payload: 'hi'
+    } ) );
+  } );
+} );

package/src/activity_integration/events.spec.js

@@ -13,6 +13,9 @@ vi.mock( '#bus', () => ( {
 
 import { emitEvent } from './events.js';
 
+// `eventId` stamping is the bus layer's responsibility (see bus.spec.js + the
+// integration tests in event_id_integration.spec.js). Assertions here use
+// `objectContaining` so they don't have to know about that enrichment.
 describe( 'emitEvent', () => {
   beforeEach( () => {
     vi.clearAllMocks();
@@ -26,12 +29,12 @@ describe( 'emitEvent', () => {
 
     emitEvent( 'cost:llm:request', { modelId: 'gpt-4o' } );
 
-    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:llm:request', {
+    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:llm:request', expect.objectContaining( {
       workflowId: 'wf-1',
       runId: 'run-1',
       activityId: 'act-1',
       modelId: 'gpt-4o'
-    } );
+    } ) );
   } );
 
   it( 'handles missing executionContext gracefully', () => {
@@ -39,12 +42,12 @@ describe( 'emitEvent', () => {
 
     emitEvent( 'foo:bar', { x: 1 } );
 
-    expect( emitMock ).toHaveBeenCalledWith( 'external:foo:bar', {
+    expect( emitMock ).toHaveBeenCalledWith( 'external:foo:bar', expect.objectContaining( {
       workflowId: undefined,
       runId: undefined,
       activityId: undefined,
       x: 1
-    } );
+    } ) );
   } );
 
   it( 'handles missing payload', () => {
@@ -55,11 +58,11 @@ describe( 'emitEvent', () => {
 
     emitEvent( 'lifecycle:start' );
 
-    expect( emitMock ).toHaveBeenCalledWith( 'external:lifecycle:start', {
+    expect( emitMock ).toHaveBeenCalledWith( 'external:lifecycle:start', expect.objectContaining( {
       workflowId: 'wf-2',
       runId: 'run-2',
       activityId: 'act-2'
-    } );
+    } ) );
   } );
 
   it( 'does not let payload override workflowId / runId / activityId', () => {
@@ -77,11 +80,11 @@ describe( 'emitEvent', () => {
 
     // Context fields are spread after the payload, so caller-supplied
     // workflowId / runId / activityId cannot escape the executionContext.
-    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:http:request', {
+    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:http:request', expect.objectContaining( {
       workflowId: 'wf-3',
       runId: 'run-3',
       activityId: 'act-3',
       url: 'https://example.com'
-    } );
+    } ) );
   } );
 } );

package/src/bus.js

@@ -1,3 +1,21 @@
 import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { isPlainObject } from '#utils';
 
-export const messageBus = new EventEmitter();
+const emitter = new EventEmitter();
+const originalEmit = emitter.emit.bind( emitter );
+
+const attachEventId = payload => ( { ...payload, eventId: payload.eventId ?? randomUUID() } );
+
+/**
+ * Every object payload emitted through `messageBus` is stamped with a UUID v4 `eventId`.
+ */
+emitter.emit = ( event, ...args ) => {
+  const [ payload, ...rest ] = args;
+  if ( !isPlainObject( payload ) ) {
+    return originalEmit( event, ...args );
+  }
+  return originalEmit( event, attachEventId( payload ), ...rest );
+};
+
+export const messageBus = emitter;

package/src/bus.spec.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { messageBus } from './bus.js';
+
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+describe( 'messageBus', () => {
+  beforeEach( () => {
+    messageBus.removeAllListeners();
+  } );
+
+  describe( 'eventId stamping', () => {
+    it( 'stamps a UUID v4 eventId on every object payload', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      messageBus.emit( 'test:event', { foo: 'bar' } );
+
+      expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
+        foo: 'bar',
+        eventId: expect.stringMatching( UUID_V4_REGEX )
+      } ) );
+    } );
+
+    it( 'gives distinct emits distinct eventIds', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      messageBus.emit( 'test:event', { i: 1 } );
+      messageBus.emit( 'test:event', { i: 2 } );
+
+      const first = handler.mock.calls[0][0].eventId;
+      const second = handler.mock.calls[1][0].eventId;
+      expect( first ).toMatch( UUID_V4_REGEX );
+      expect( second ).toMatch( UUID_V4_REGEX );
+      expect( first ).not.toBe( second );
+    } );
+
+    it( 'preserves a caller-supplied eventId (deterministic retry case)', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      messageBus.emit( 'test:event', { eventId: 'fixed-id', foo: 'bar' } );
+
+      expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
+        eventId: 'fixed-id',
+        foo: 'bar'
+      } ) );
+    } );
+
+    it( 'does not mutate the caller-supplied payload object', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      const payload = { foo: 'bar' };
+      messageBus.emit( 'test:event', payload );
+
+      expect( payload ).not.toHaveProperty( 'eventId' );
+    } );
+  } );
+
+  describe( 'pass-through behavior', () => {
+    it( 'passes primitive payloads through unchanged', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      messageBus.emit( 'test:event', 'a-string' );
+      messageBus.emit( 'test:event', 42 );
+      messageBus.emit( 'test:event', true );
+
+      expect( handler ).toHaveBeenNthCalledWith( 1, 'a-string' );
+      expect( handler ).toHaveBeenNthCalledWith( 2, 42 );
+      expect( handler ).toHaveBeenNthCalledWith( 3, true );
+    } );
+
+    it( 'passes null and undefined payloads through unchanged', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      messageBus.emit( 'test:event', null );
+      messageBus.emit( 'test:event' );
+
+      expect( handler ).toHaveBeenNthCalledWith( 1, null );
+      expect( handler ).toHaveBeenNthCalledWith( 2 );
+    } );
+
+    it( 'passes array payloads through unchanged (no key injection)', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      messageBus.emit( 'test:event', [ 1, 2, 3 ] );
+
+      expect( handler ).toHaveBeenCalledWith( [ 1, 2, 3 ] );
+    } );
+
+    it( 'forwards additional positional args untouched', () => {
+      const handler = vi.fn();
+      messageBus.on( 'test:event', handler );
+
+      messageBus.emit( 'test:event', { foo: 'bar' }, 'extra', 99 );
+
+      expect( handler ).toHaveBeenCalledWith(
+        expect.objectContaining( { foo: 'bar', eventId: expect.stringMatching( UUID_V4_REGEX ) } ),
+        'extra',
+        99
+      );
+    } );
+  } );
+} );

package/src/hooks/index.d.ts

@@ -2,6 +2,8 @@
  * Payload passed to the onError handler when a workflow, activity or runtime error occurs.
  */
 export interface ErrorHookPayload {
+  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
+  eventId: string;
   /** Origin of the error: workflow execution, activity execution, or runtime. */
   source: 'workflow' | 'activity' | 'runtime';
   /** Name of the workflow, when the error is scoped to a workflow or activity. */
@@ -16,6 +18,8 @@ export interface ErrorHookPayload {
  * Payload passed to the onWorkflowStart handler when a workflow run begins.
  */
 export interface WorkflowStartHookPayload {
+  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
+  eventId: string;
   /** Workflow id (stable across retries / continue-as-new). */
   id: string;
   /** Temporal run id for the current execution attempt. */
@@ -28,6 +32,8 @@ export interface WorkflowStartHookPayload {
  * Payload passed to the onWorkflowEnd handler when a workflow run completes successfully.
  */
 export interface WorkflowEndHookPayload {
+  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
+  eventId: string;
   /** Workflow id (stable across retries / continue-as-new). */
   id: string;
   /** Temporal run id for the current execution attempt. */
@@ -42,6 +48,8 @@ export interface WorkflowEndHookPayload {
  * Payload passed to the onWorkflowError handler when a workflow run fails.
  */
 export interface WorkflowErrorHookPayload {
+  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
+  eventId: string;
   /** Workflow id (stable across retries / continue-as-new). */
   id: string;
   /** Temporal run id for the current execution attempt. */
@@ -107,6 +115,8 @@ export declare function onWorkflowError( handler: ( payload: WorkflowErrorHookPa
  * to the fields listed here.
  */
 export interface HttpRequestHookPayload {
+  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
+  eventId: string;
   /** Workflow id (stable across retries / continue-as-new). */
   workflowId: string;
   /** Temporal run id for the current execution attempt. */

package/src/hooks/index.js

@@ -21,12 +21,12 @@ const safeInvoke = async ( fn, args, hookName ) => {
 
 /** Triggers on any errors: workflow, activity and runtime */
 export const onError = handler => {
-  messageBus.on( BusEventType.ACTIVITY_ERROR, async ( { id, name, workflowId, workflowName, error } ) =>
-    safeInvoke( handler, { source: 'activity', activityId: id, activityName: name, workflowId, workflowName, error }, 'onError' ) );
-  messageBus.on( BusEventType.WORKFLOW_ERROR, async ( { id, name, error } ) =>
-    safeInvoke( handler, { source: 'workflow', workflowId: id, workflowName: name, error }, 'onError' ) );
-  messageBus.on( BusEventType.RUNTIME_ERROR, async ( { error } ) =>
-    safeInvoke( handler, { source: 'runtime', error }, 'onError' ) );
+  messageBus.on( BusEventType.ACTIVITY_ERROR, async ( { eventId, id, name, workflowId, workflowName, error } ) =>
+    safeInvoke( handler, { eventId, source: 'activity', activityId: id, activityName: name, workflowId, workflowName, error }, 'onError' ) );
+  messageBus.on( BusEventType.WORKFLOW_ERROR, async ( { eventId, id, name, error } ) =>
+    safeInvoke( handler, { eventId, source: 'workflow', workflowId: id, workflowName: name, error }, 'onError' ) );
+  messageBus.on( BusEventType.RUNTIME_ERROR, async ( { eventId, error } ) =>
+    safeInvoke( handler, { eventId, source: 'runtime', error }, 'onError' ) );
 };
 
 /** Listen to worker before start events */
@@ -34,16 +34,16 @@ export const onBeforeWorkerStart = handler => messageBus.on( BusEventType.WORKER
   safeInvoke( handler, undefined, 'onBeforeWorkerStart' ) );
 
 /** Listen to workflow start events, excludes catalog workflow */
-export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { id, runId, name } ) =>
-  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, runId, name }, 'onWorkflowStart' ) : null );
+export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { eventId, id, runId, name } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { eventId, id, runId, name }, 'onWorkflowStart' ) : null );
 
 /** Listen to workflow end events, excludes catalog workflow */
-export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { id, runId, name, duration } ) =>
-  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, runId, name, duration }, 'onWorkflowEnd' ) : null );
+export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { eventId, id, runId, name, duration } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { eventId, id, runId, name, duration }, 'onWorkflowEnd' ) : null );
 
 /** Listen to workflow error events, excludes catalog workflow */
-export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { id, runId, name, duration, error } ) =>
-  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, runId, name, duration, error }, 'onWorkflowError' ) : null );
+export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { eventId, id, runId, name, duration, error } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { eventId, id, runId, name, duration, error }, 'onWorkflowError' ) : null );
 
 /** Generic listener for events emitted elsewhere (outside core) */
 export const on = ( eventName, handler ) => messageBus.on( `external:${eventName}`, payload =>

package/src/hooks/index.spec.js

@@ -43,12 +43,13 @@ describe( 'hooks/index', () => {
       expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.RUNTIME_ERROR, expect.any( Function ) );
     } );
 
-    it( 'invokes handler with activity-shaped payload', async () => {
+    it( 'invokes handler with activity-shaped payload, forwarding eventId', async () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       onError( handler );
 
       const err = new Error( 'act-fail' );
       await onHandlers[BusEventType.ACTIVITY_ERROR]( {
+        eventId: 'evt-act-1',
         id: 'act-1',
         name: 'wf#step',
         workflowId: 'wf-run-1',
@@ -57,6 +58,7 @@ describe( 'hooks/index', () => {
       } );
 
       expect( handler ).toHaveBeenCalledWith( {
+        eventId: 'evt-act-1',
         source: 'activity',
         activityId: 'act-1',
         activityName: 'wf#step',
@@ -66,18 +68,20 @@ describe( 'hooks/index', () => {
       } );
     } );
 
-    it( 'invokes handler with workflow-shaped payload', async () => {
+    it( 'invokes handler with workflow-shaped payload, forwarding eventId', async () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       onError( handler );
 
       const err = new Error( 'wf-fail' );
       await onHandlers[BusEventType.WORKFLOW_ERROR]( {
+        eventId: 'evt-wf-1',
         id: 'wf-run-2',
         name: 'myWorkflow',
         error: err
       } );
 
       expect( handler ).toHaveBeenCalledWith( {
+        eventId: 'evt-wf-1',
         source: 'workflow',
         workflowId: 'wf-run-2',
         workflowName: 'myWorkflow',
@@ -90,9 +94,9 @@ describe( 'hooks/index', () => {
       onError( handler );
 
       const error = new Error( 'rt' );
-      await onHandlers[BusEventType.RUNTIME_ERROR]( { error } );
+      await onHandlers[BusEventType.RUNTIME_ERROR]( { eventId: 'evt-rt-1', error } );
 
-      expect( handler ).toHaveBeenCalledWith( { source: 'runtime', error } );
+      expect( handler ).toHaveBeenCalledWith( { eventId: 'evt-rt-1', source: 'runtime', error } );
     } );
   } );
 
@@ -109,56 +113,60 @@ describe( 'hooks/index', () => {
   } );
 
   describe( 'onWorkflowStart', () => {
-    it( 'skips catalog workflow name', async () => {
+    it( 'skips catalog workflow and forwards eventId for real workflows', async () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       onWorkflowStart( handler );
 
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( { id: '1', name: WORKFLOW_CATALOG } ) );
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( {
+        eventId: 'evt-ignored', id: '1', name: WORKFLOW_CATALOG
+      } ) );
       expect( handler ).not.toHaveBeenCalled();
 
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( { id: '2', name: 'myWorkflow' } ) );
-      expect( handler ).toHaveBeenCalledWith( { id: '2', name: 'myWorkflow' } );
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( {
+        eventId: 'evt-start-1', id: '2', runId: 'run-2', name: 'myWorkflow'
+      } ) );
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: 'evt-start-1', id: '2', runId: 'run-2', name: 'myWorkflow'
+      } );
     } );
   } );
 
   describe( 'onWorkflowEnd', () => {
-    it( 'skips catalog workflow name', async () => {
+    it( 'skips catalog workflow and forwards eventId for real workflows', async () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       onWorkflowEnd( handler );
 
       await Promise.resolve( onHandlers[BusEventType.WORKFLOW_END]( {
-        id: '1',
-        name: WORKFLOW_CATALOG,
-        duration: 10
+        eventId: 'evt-ignored', id: '1', name: WORKFLOW_CATALOG, duration: 10
       } ) );
       expect( handler ).not.toHaveBeenCalled();
 
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_END]( { id: '2', name: 'myWorkflow', duration: 5 } ) );
-      expect( handler ).toHaveBeenCalledWith( { id: '2', name: 'myWorkflow', duration: 5 } );
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_END]( {
+        eventId: 'evt-end-1', id: '2', runId: 'run-2', name: 'myWorkflow', duration: 5
+      } ) );
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: 'evt-end-1', id: '2', runId: 'run-2', name: 'myWorkflow', duration: 5
+      } );
     } );
   } );
 
   describe( 'onWorkflowError', () => {
-    it( 'skips catalog workflow name', async () => {
+    it( 'skips catalog workflow and forwards eventId for real workflows', async () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       const err = new Error( 'wf' );
       onWorkflowError( handler );
 
       await Promise.resolve( onHandlers[BusEventType.WORKFLOW_ERROR]( {
-        id: '1',
-        name: WORKFLOW_CATALOG,
-        duration: 1,
-        error: err
+        eventId: 'evt-ignored', id: '1', name: WORKFLOW_CATALOG, duration: 1, error: err
       } ) );
       expect( handler ).not.toHaveBeenCalled();
 
       await Promise.resolve( onHandlers[BusEventType.WORKFLOW_ERROR]( {
-        id: '2',
-        name: 'myWorkflow',
-        duration: 2,
-        error: err
+        eventId: 'evt-err-1', id: '2', runId: 'run-2', name: 'myWorkflow', duration: 2, error: err
       } ) );
-      expect( handler ).toHaveBeenCalledWith( { id: '2', name: 'myWorkflow', duration: 2, error: err } );
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: 'evt-err-1', id: '2', runId: 'run-2', name: 'myWorkflow', duration: 2, error: err
+      } );
     } );
   } );