@outputai/core 0.10.1-dev.b7b2fbe.0 → 0.10.1-next.09ed166.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.10.1-dev.b7b2fbe.0",
+  "version": "0.10.1-next.09ed166.0",
   "description": "The core module of the output framework",
   "type": "module",
   "engines": {

package/src/bus.js

@@ -1,30 +1,68 @@
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
-import { isPlainObject } from '#helpers/object';
+import { Storage } from '#async_storage';
+import { WORKFLOW_CATALOG } from '#consts';
 
-const emitter = new EventEmitter();
+const mainEventBus = new EventEmitter();
+const stepEventBus = new EventEmitter();
+
+const getContext = () => {
+  const ctx = Storage.load();
+  if ( ctx ) {
+    const { outputActivityKind, activityInfo, workflowDetails } = ctx;
+    return { outputActivityKind, activityInfo, workflowDetails };
+  }
+  return {};
+};
 
 /**
- * Every object payload emitted through `messageBus` is stamped with a UUID v4 `eventId`.
+ * Attaches information and filter out events from the bus by proxying .emit().
+ *
+ * If createEnvelope=true, wrap payload:
+ * ```js
+ * {
+ *   eventId,
+ *   eventDate,
+ *   outputActivityKind,
+ *   activityInfo,
+ *   workflowDetails,
+ *   payload: <original payload>
+ * }
+ * ```
+ *
+ * if createEnvelope=false, adds eventId and eventDate to the original payload object
+ *
+ * @param {object} args
+ * @param {object} args.bus The event emitter to proxy
+ * @param {boolean} args.createEnvelope Whether to wrap event around an envelope
+ * @param {function} args.filter Filter function to drop events
  */
-emitter.emit = new Proxy( emitter.emit, {
-  apply( target, thisArg, args ) {
-    const [ eventName, payload, ...extras ] = args;
-    const newArguments = [];
-
-    // do now push arguments that dont exist. if payload is undefined with len=1, means it was never defined
-    // if payload is undefined with len>1, means user passed 'undefined' as argument
-    if ( args.length > 1 ) {
-      newArguments.push( isPlainObject( payload ) ? {
+const proxyBus = ( { bus, createEnvelope = false, filter } ) => {
+  bus.emit = new Proxy( bus.emit, {
+    apply( target, thisArg, args ) {
+      const [ eventName, payload, ...rest ] = args;
+
+      const shouldEmit = filter?.( eventName, payload ) ?? true;
+      if ( !shouldEmit ) {
+        return false;
+      }
+
+      const eventFields = {
         eventId: randomUUID(),
-        eventDate: Date.now(),
-        ...payload
-      } : payload );
-      newArguments.push( ...extras );
+        eventDate: Date.now()
+      };
+
+      const newPayload = createEnvelope ? { ...eventFields, ...getContext(), payload } : { ...eventFields, ...payload };
+      return Reflect.apply( target, thisArg, [ eventName, newPayload, ...rest ] );
     }
+  } );
+};
 
-    return Reflect.apply( target, thisArg, [ eventName, ...newArguments ] );
-  }
-} );
+const catalogWfFilter = ( _, payload ) => payload?.workflowDetails?.workflowType !== WORKFLOW_CATALOG;
+
+// Main bus is not used inside steps, so it doesn't need context
+proxyBus( { bus: mainEventBus, createEnvelope: false, filter: catalogWfFilter } );
+// This receives SDK and user events from within steps, so add context to it
+proxyBus( { bus: stepEventBus, createEnvelope: true } );
 
-export const messageBus = emitter;
+export { mainEventBus, stepEventBus };

package/src/bus.spec.js

@@ -1,135 +1,193 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { messageBus } from './bus.js';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const loadMock = vi.hoisted( () => vi.fn() );
+
+vi.mock( '#async_storage', () => ( {
+  Storage: { load: loadMock }
+} ) );
+
+import { mainEventBus, stepEventBus } 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;
+const ACTIVITY_CONTEXT = {
+  activityInfo: { activityId: 'activity-id' },
+  workflowDetails: { workflowId: 'workflow-id' },
+  outputActivityKind: 'step'
+};
 
-describe( 'messageBus', () => {
+describe( 'event buses', () => {
   beforeEach( () => {
-    messageBus.removeAllListeners();
+    mainEventBus.removeAllListeners();
+    stepEventBus.removeAllListeners();
+    loadMock.mockReset();
   } );
 
-  describe( 'eventId stamping', () => {
-    it( 'stamps a UUID v4 eventId on every object payload', () => {
+  afterEach( () => {
+    vi.useRealTimers();
+  } );
+
+  describe( 'mainEventBus', () => {
+    it( 'adds event metadata to payload fields', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      const now = new Date( '2026-06-02T12:00:00.000Z' );
+      vi.useFakeTimers();
+      vi.setSystemTime( now );
+      mainEventBus.on( 'test:event', handler );
 
-      messageBus.emit( 'test:event', { foo: 'bar' } );
+      mainEventBus.emit( 'test:event', { foo: 'bar' } );
 
-      expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
-        foo: 'bar',
-        eventId: expect.stringMatching( UUID_V4_REGEX )
-      } ) );
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: expect.stringMatching( UUID_V4_REGEX ),
+        eventDate: now.getTime(),
+        foo: 'bar'
+      } );
     } );
 
-    it( 'gives distinct emits distinct eventIds', () => {
+    it( 'preserves caller-supplied event metadata', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      mainEventBus.on( 'test:event', handler );
 
-      messageBus.emit( 'test:event', { i: 1 } );
-      messageBus.emit( 'test:event', { i: 2 } );
+      mainEventBus.emit( 'test:event', { eventId: 'fixed-id', eventDate: 1234 } );
 
-      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 );
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: 'fixed-id',
+        eventDate: 1234
+      } );
     } );
 
-    it( 'preserves a caller-supplied eventId (deterministic retry case)', () => {
+    it( 'does not mutate the caller-supplied payload', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      const payload = { foo: 'bar' };
+      mainEventBus.on( 'test:event', handler );
 
-      messageBus.emit( 'test:event', { eventId: 'fixed-id', foo: 'bar' } );
+      mainEventBus.emit( 'test:event', payload );
 
-      expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
-        eventId: 'fixed-id',
-        foo: 'bar'
+      expect( handler.mock.calls[0][0] ).not.toBe( payload );
+      expect( payload ).toEqual( { foo: 'bar' } );
+    } );
+
+    it( 'does not attach activity context', () => {
+      const handler = vi.fn();
+      loadMock.mockReturnValue( {
+        activityInfo: { activityId: 'activity-id' },
+        workflowDetails: { workflowId: 'workflow-id' },
+        outputActivityKind: 'step'
+      } );
+      mainEventBus.on( 'test:event', handler );
+
+      mainEventBus.emit( 'test:event', { foo: 'bar' } );
+
+      expect( handler ).toHaveBeenCalledWith( expect.not.objectContaining( {
+        activityInfo: expect.anything(),
+        workflowDetails: expect.anything(),
+        outputActivityKind: expect.anything()
       } ) );
+      expect( loadMock ).not.toHaveBeenCalled();
     } );
 
-    it( 'stamps eventDate on every object payload', () => {
+    it( 'filters catalog workflow events', () => {
       const handler = vi.fn();
-      const now = new Date( '2026-06-02T12:00:00.000Z' );
-      vi.useFakeTimers();
-      vi.setSystemTime( now );
-      messageBus.on( 'test:event', handler );
+      mainEventBus.on( 'workflow:start', handler );
 
-      messageBus.emit( 'test:event', { foo: 'bar' } );
+      const emitted = mainEventBus.emit( 'workflow:start', {
+        workflowDetails: { workflowType: '$catalog' }
+      } );
 
-      expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
-        eventDate: now.getTime(),
-        foo: 'bar'
-      } ) );
+      expect( emitted ).toBe( false );
+      expect( handler ).not.toHaveBeenCalled();
+    } );
+  } );
 
-      vi.useRealTimers();
+  describe( 'stepEventBus', () => {
+    beforeEach( () => {
+      loadMock.mockReturnValue( ACTIVITY_CONTEXT );
     } );
 
-    it( 'preserves a caller-supplied eventDate', () => {
+    it( 'wraps payloads with event metadata and activity context', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      const payload = { foo: 'bar' };
+      stepEventBus.on( 'test:event', handler );
 
-      messageBus.emit( 'test:event', { eventDate: 1234, foo: 'bar' } );
+      stepEventBus.emit( 'test:event', payload );
 
-      expect( handler ).toHaveBeenCalledWith( expect.objectContaining( {
-        eventDate: 1234,
-        foo: 'bar'
-      } ) );
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: expect.stringMatching( UUID_V4_REGEX ),
+        eventDate: expect.any( Number ),
+        ...ACTIVITY_CONTEXT,
+        payload
+      } );
     } );
 
-    it( 'does not mutate the caller-supplied payload object', () => {
+    it( 'omits activity fields outside activity context', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      loadMock.mockReturnValue( undefined );
+      stepEventBus.on( 'test:event', handler );
 
-      const payload = { foo: 'bar' };
-      messageBus.emit( 'test:event', payload );
+      stepEventBus.emit( 'test:event', { foo: 'bar' } );
 
-      expect( payload ).not.toHaveProperty( 'eventId' );
-      expect( payload ).not.toHaveProperty( 'eventDate' );
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: expect.stringMatching( UUID_V4_REGEX ),
+        eventDate: expect.any( Number ),
+        payload: { foo: 'bar' }
+      } );
     } );
-  } );
 
-  describe( 'pass-through behavior', () => {
-    it( 'passes primitive payloads through unchanged', () => {
+    it( 'preserves arbitrary payloads unchanged inside the envelope', () => {
       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 );
+      const array = [ 1, 2, 3 ];
+      const instance = new Date();
+      stepEventBus.on( 'test:event', handler );
+
+      stepEventBus.emit( 'test:event', 'value' );
+      stepEventBus.emit( 'test:event', array );
+      stepEventBus.emit( 'test:event', instance );
+      stepEventBus.emit( 'test:event' );
+
+      expect( handler.mock.calls[0][0].payload ).toBe( 'value' );
+      expect( handler.mock.calls[1][0].payload ).toBe( array );
+      expect( handler.mock.calls[2][0].payload ).toBe( instance );
+      expect( handler.mock.calls[3][0] ).toHaveProperty( 'payload', undefined );
     } );
 
-    it( 'passes null and undefined payloads through unchanged', () => {
+    it( 'keeps payload metadata separate from envelope metadata', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      const payload = { eventId: 'payload-id', eventDate: 1234 };
+      stepEventBus.on( 'test:event', handler );
 
-      messageBus.emit( 'test:event', null );
-      messageBus.emit( 'test:event' );
+      stepEventBus.emit( 'test:event', payload );
 
-      expect( handler ).toHaveBeenNthCalledWith( 1, null );
-      expect( handler ).toHaveBeenNthCalledWith( 2 );
+      const envelope = handler.mock.calls[0][0];
+      expect( envelope.eventId ).toMatch( UUID_V4_REGEX );
+      expect( envelope.eventId ).not.toBe( payload.eventId );
+      expect( envelope.eventDate ).not.toBe( payload.eventDate );
+      expect( envelope.payload ).toBe( payload );
     } );
 
-    it( 'passes array payloads through unchanged (no key injection)', () => {
+    it( 'gives distinct emits distinct eventIds', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      stepEventBus.on( 'test:event', handler );
 
-      messageBus.emit( 'test:event', [ 1, 2, 3 ] );
+      stepEventBus.emit( 'test:event', { i: 1 } );
+      stepEventBus.emit( 'test:event', { i: 2 } );
 
-      expect( handler ).toHaveBeenCalledWith( [ 1, 2, 3 ] );
+      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( 'forwards additional positional args untouched', () => {
+    it( 'forwards additional positional arguments unchanged', () => {
       const handler = vi.fn();
-      messageBus.on( 'test:event', handler );
+      stepEventBus.on( 'test:event', handler );
 
-      messageBus.emit( 'test:event', { foo: 'bar' }, 'extra', 99 );
+      stepEventBus.emit( 'test:event', { foo: 'bar' }, 'extra', 99 );
 
       expect( handler ).toHaveBeenCalledWith(
-        expect.objectContaining( { foo: 'bar', eventId: expect.stringMatching( UUID_V4_REGEX ) } ),
+        expect.objectContaining( {
+          eventId: expect.stringMatching( UUID_V4_REGEX ),
+          payload: { foo: 'bar' }
+        } ),
         'extra',
         99
       );

package/src/helpers/object.js

@@ -44,7 +44,11 @@ export const deepMergeWithResolver = ( base, ...args ) => {
   const resolver = args.at( -1 );
 
   if ( !isPlainObject( base ) ) {
-    throw new Error( 'First argument is not an object.' );
+    throw new Error( 'First argument (base object) is not an object.' );
+  }
+
+  if ( typeof resolver !== 'function' ) {
+    throw new Error( 'Last argument (resolver) is not a function.' );
   }
 
   return objects.reduce( ( merged, object ) => {

package/src/helpers/object.spec.js

@@ -224,6 +224,11 @@ describe( 'deepMergeWithResolver', () => {
     expect( () => deepMergeWithResolver( 'a', {}, ( x, y ) => x + y ) ).toThrow( Error );
   } );
 
+  it( 'throws when last argument is not a resolver function', () => {
+    expect( () => deepMergeWithResolver( { a: 1 }, { a: 2 } ) )
+      .toThrow( 'Last argument (resolver) is not a function.' );
+  } );
+
   it( 'merges multiple objects using the resolver from left to right', () => {
     const resolver = vi.fn( ( x, y ) => `${ x }:${ y }` );
 

package/src/hooks/index.d.ts

@@ -99,35 +99,19 @@ export interface Aggregations {
 }
 
 /**
- * Common lifecycle hook payload fields for events associated with a workflow.
+ * Common hook payload fields
  */
 export interface HookPayloadBase {
   /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
   eventId: string;
   /** Timestamp of the event */
   eventDate: number;
-  /** Information about the current workflow execution */
-  workflowDetails: WorkflowDetails;
-}
-
-/**
- * Common hook payload fields for events associated with an activity.
- */
-export interface ActivityPayloadBase extends HookPayloadBase {
-  /** Temporal's activityInfo(). */
-  activityInfo: Info;
-  /** Output component kind for the activity, e.g. step or evaluator. */
-  outputActivityKind: string;
 }
 
 /**
  * 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;
-  /** Timestamp of the event */
-  eventDate: number;
+export interface ErrorHookPayload extends HookPayloadBase {
   /** Origin of the error: workflow execution, activity execution, or runtime. */
   source: 'workflow' | 'activity' | 'runtime';
   /** Information about the current workflow execution */
@@ -135,45 +119,60 @@ export interface ErrorHookPayload {
   /** Temporal's activityInfo(). If source is activity */
   activityInfo?: Info;
   /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
-  outputActivityKind?: string;
+  outputActivityKind: string;
   /** Attribute totals collected during the activity execution. */
   aggregations?: Aggregations | null;
   /** The error thrown. */
   error: Error;
 }
 
+/**
+ * Common hook payload fields for events associated with an workflow.
+ */
+export interface WorkflowPayloadBase extends HookPayloadBase {
+  /** Information about the current workflow execution */
+  workflowDetails: WorkflowDetails;
+}
+
 /**
  * Payload passed to the onWorkflowStart() handler when a workflow run begins.
  */
-export type WorkflowStartHookPayload = HookPayloadBase;
+export type WorkflowStartHookPayload = WorkflowPayloadBase;
 
 /**
  * Payload passed to the onWorkflowEnd() handler when a workflow run completes successfully.
  */
-export type WorkflowEndHookPayload = HookPayloadBase;
+export type WorkflowEndHookPayload = WorkflowPayloadBase;
 
 /**
  * Payload passed to the onWorkflowError() handler when a workflow run fails.
  */
-export interface WorkflowErrorHookPayload extends HookPayloadBase {
+export interface WorkflowErrorHookPayload extends WorkflowPayloadBase {
   /** The error thrown. */
   error: Error;
 }
 
 /**
- * Common activity lifecycle hook payload fields.
+ * Common hook payload fields for events associated with an activity.
  */
-export type ActivityHookPayload = ActivityPayloadBase;
+export interface ActivityPayloadBase extends HookPayloadBase {
+  /** Information about the current workflow execution */
+  workflowDetails: WorkflowDetails;
+  /** Temporal's activityInfo(). */
+  activityInfo: Info;
+  /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
+  outputActivityKind: string;
+}
 
 /**
  * Payload passed to the onActivityStart() handler when an activity starts.
  */
-export type ActivityStartHookPayload = ActivityHookPayload;
+export type ActivityStartHookPayload = ActivityPayloadBase;
 
 /**
  * Payload passed to the onActivityEnd() handler when an activity completes successfully.
  */
-export interface ActivityEndHookPayload extends ActivityHookPayload {
+export interface ActivityEndHookPayload extends ActivityPayloadBase {
   /** Attribute totals collected during the activity execution. */
   aggregations: Aggregations | null;
 }
@@ -181,7 +180,7 @@ export interface ActivityEndHookPayload extends ActivityHookPayload {
 /**
  * Payload passed to the onActivityError() handler when an activity fails.
  */
-export interface ActivityErrorHookPayload extends ActivityHookPayload {
+export interface ActivityErrorHookPayload extends ActivityPayloadBase {
   /** Attribute totals collected during the activity execution. */
   aggregations: Aggregations | null;
   /** The error thrown. */
@@ -233,8 +232,6 @@ export declare function onWorkflowError( handler: ( payload: WorkflowErrorHookPa
 /**
  * Register a handler to be invoked when an activity starts.
  *
- * Excludes internal activities.
- *
  * @param handler - Function called with the activity start payload.
  */
 export declare function onActivityStart( handler: ( payload: ActivityStartHookPayload ) => void ): void;
@@ -242,8 +239,6 @@ export declare function onActivityStart( handler: ( payload: ActivityStartHookPa
 /**
  * Register a handler to be invoked when an activity completes successfully.
  *
- * Excludes internal activities.
- *
  * @param handler - Function called with the activity end payload.
  */
 export declare function onActivityEnd( handler: ( payload: ActivityEndHookPayload ) => void ): void;
@@ -251,24 +246,32 @@ export declare function onActivityEnd( handler: ( payload: ActivityEndHookPayloa
 /**
  * Register a handler to be invoked when an activity fails.
  *
- * Excludes internal activities.
- *
  * @param handler - Function called with the activity error payload.
  */
 export declare function onActivityError( handler: ( payload: ActivityErrorHookPayload ) => void ): void;
 
-/**
- * Framework-managed envelope added to payloads passed to on() handlers.
- */
-export interface OnHookEnvelope extends HookPayloadBase {
-  /** Temporal's activityInfo(). */
-  activityInfo: Info;
-  /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
+/** Framework metadata, optional activity context, and the emitted payload. */
+export type ExternalHookPayload<TPayload = unknown> = HookPayloadBase & {
+  /** Information about the current workflow execution, when emitted from an activity. */
+  workflowDetails?: WorkflowDetails;
+  /** Temporal's activityInfo(), when emitted from an activity. */
+  activityInfo?: Info;
+  /** Output component kind, when emitted from an activity. */
   outputActivityKind?: string;
-}
+  /** The emitted payload */
+  payload: TPayload | undefined;
+};
 
-export type OnHookPayload<TAttributes extends Record<string, unknown> = Record<string, unknown>> =
-  OnHookEnvelope & TAttributes;
+/**
+ * Emit a custom event from the current activity.
+ *
+ * @param eventName - The name of the event to emit.
+ * @param payload - Optional value forwarded to on() handlers.
+ */
+export declare function emit(
+  eventName: string,
+  payload?: unknown
+): boolean;
 
 /**
  * Register a handler to be invoked when a given event happens
@@ -276,7 +279,7 @@ export type OnHookPayload<TAttributes extends Record<string, unknown> = Record<s
  * @param eventName - The name of the event to subscribe
  * @param handler - Function called with the event payload
  */
-export declare function on<TAttributes extends Record<string, unknown> = Record<string, unknown>>(
+export declare function on<TPayload = unknown>(
   eventName: string,
-  handler: ( payload: OnHookPayload<TAttributes> ) => void
+  handler: ( event: ExternalHookPayload<TPayload> ) => void
 ): void;