@outputai/core 0.10.1-dev.b7b2fbe.0 → 0.10.1-next.2caa4a1.0

package/src/hooks/index.js

@@ -1,68 +1,75 @@
-import { messageBus } from '#bus';
-import { BusEventType, ComponentType, WORKFLOW_CATALOG } from '#consts';
+import { mainEventBus, stepEventBus } from '#bus';
+import { BusEventType } from '#consts';
 import { createChildLogger } from '#logger';
+import { pendingHooks } from './pending_hooks.js';
 
 const log = createChildLogger( 'Hooks' );
 
 /**
- * Invokes an external hook handler function with a try catch around it
+ * Invokes a function within a try catch and log the error.
  *
  * @param {Function} fn
  * @param {any} args - Args to invoke the function with
  * @param {string} hookName - hookName to identify this hook function in the logs
  */
-const safeInvoke = async ( fn, args, hookName ) => {
-  try {
-    await fn( args );
-  } catch ( error ) {
-    log.error( `${hookName} hook error`, { message: error.message, stack: error.stack } );
-  }
+const callHookCb = ( fn, args, hookName ) => {
+  const promise = Promise.resolve()
+    .then( () => fn( args ) )
+    .catch( e => log.error( `${hookName} hook error`, { message: e.message, stack: e.stack } ) )
+    .finally( () => pendingHooks.delete( promise ) );
+  pendingHooks.add( promise );
+  return promise;
 };
 
-/** Triggers on any errors: workflow, activity and runtime */
-export const onError = handler => {
-  messageBus.on( BusEventType.ACTIVITY_ERROR, async payload =>
-    safeInvoke( handler, { source: 'activity', ...payload }, 'onError' ) );
-  messageBus.on( BusEventType.WORKFLOW_ERROR, async payload =>
-    safeInvoke( handler, { source: 'workflow', ...payload }, 'onError' ) );
-  messageBus.on( BusEventType.RUNTIME_ERROR, async payload =>
-    safeInvoke( handler, { source: 'runtime', ...payload }, 'onError' ) );
+// General Life-cycle
+// --------------------------------------
+const onError = cb => {
+  mainEventBus.on( BusEventType.ACTIVITY_ERROR, async payload =>
+    callHookCb( cb, { source: 'activity', ...payload }, 'onError' ) );
+  mainEventBus.on( BusEventType.WORKFLOW_ERROR, async payload =>
+    callHookCb( cb, { source: 'workflow', ...payload }, 'onError' ) );
+  mainEventBus.on( BusEventType.RUNTIME_ERROR, async payload =>
+    callHookCb( cb, { source: 'runtime', ...payload }, 'onError' ) );
 };
 
-/** Listen to worker before start events */
-export const onBeforeWorkerStart = handler => messageBus.on( BusEventType.WORKER_BEFORE_START, () =>
-  safeInvoke( handler, undefined, 'onBeforeWorkerStart' ) );
+const onBeforeWorkerStart = cb => mainEventBus.on( BusEventType.WORKER_BEFORE_START, () => callHookCb( cb, undefined, 'onBeforeWorkerStart' ) );
 
-/** Catalog workflow events should not be emitted */
-const shouldEmitWorkflowEvent = workflowDetails => WORKFLOW_CATALOG !== workflowDetails.workflowType;
+// Workflow Life-cycle
+// --------------------------------------
+const onWorkflowStart = cb => mainEventBus.on( BusEventType.WORKFLOW_START, payload => callHookCb( cb, payload, 'onWorkflowStart' ) );
+const onWorkflowEnd = cb => mainEventBus.on( BusEventType.WORKFLOW_END, payload => callHookCb( cb, payload, 'onWorkflowEnd' ) );
+const onWorkflowError = cb => mainEventBus.on( BusEventType.WORKFLOW_ERROR, payload => callHookCb( cb, payload, 'onWorkflowError' ) );
 
-/** Listen to workflow start events, excludes catalog workflow */
-export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowStart' ) : null );
+// Activity Life-cycle
+// --------------------------------------
+const onActivityStart = cb => mainEventBus.on( BusEventType.ACTIVITY_START, fields => callHookCb( cb, fields, 'onActivityStart' ) );
+const onActivityEnd = cb => mainEventBus.on( BusEventType.ACTIVITY_END, fields => callHookCb( cb, fields, 'onActivityEnd' ) );
+const onActivityError = cb => mainEventBus.on( BusEventType.ACTIVITY_ERROR, fields => callHookCb( cb, fields, 'onActivityError' ) );
 
-/** Listen to workflow end events, excludes catalog workflow */
-export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowEnd' ) : null );
-
-/** Listen to workflow error events, excludes catalog workflow */
-export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowError' ) : null );
-
-/** Internal activities do not trigger hooks */
-const shouldEmitActivityEvent = outputActivityKind => outputActivityKind !== ComponentType.INTERNAL_STEP;
-
-/** Listen to workflow start events, excludes catalog workflow */
-export const onActivityStart = handler => messageBus.on( BusEventType.ACTIVITY_START, ( { outputActivityKind, ...eventFields } ) =>
-  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityStart' ) : null );
-
-/** Listen to workflow end events, excludes catalog workflow */
-export const onActivityEnd = handler => messageBus.on( BusEventType.ACTIVITY_END, ( { outputActivityKind, ...eventFields } ) =>
-  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityEnd' ) : null );
+// Generic Events
+// --------------------------------------
+/** Listen to both sdk and custom events */
+const on = ( eventName, cb ) => {
+  stepEventBus.on( `sdk:${eventName}`, payload => callHookCb( cb, payload, eventName ) );
+  stepEventBus.on( `usr:${eventName}`, payload => callHookCb( cb, payload, eventName ) );
+};
 
-/** Listen to workflow error events, excludes catalog workflow */
-export const onActivityError = handler => messageBus.on( BusEventType.ACTIVITY_ERROR, ( { outputActivityKind, ...eventFields } ) =>
-  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityError' ) : null );
+/**
+ * Emits a custom event
+ * @param {string} eventName
+ * @param {any} payload
+ */
+const emit = ( eventName, payload ) => stepEventBus.emit( `usr:${eventName}`, payload );
 
-/** Generic listener for events emitted elsewhere (outside core) */
-export const on = ( eventName, handler ) => messageBus.on( `external:${eventName}`, payload =>
-  safeInvoke( handler, payload, eventName ) );
+export {
+  emit,
+  on,
+  onActivityEnd,
+  onActivityError,
+  onActivityStart,
+  onBeforeWorkerStart,
+  onError,
+  onWorkflowEnd,
+  onWorkflowError,
+  onWorkflowStart
+};

package/src/hooks/index.spec.js

@@ -1,22 +1,33 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { BusEventType, ComponentType, WORKFLOW_CATALOG } from '#consts';
+import { BusEventType } from '#consts';
 
 const logErrorMock = vi.hoisted( () => vi.fn() );
 const createChildLoggerMock = vi.hoisted( () =>
   vi.fn( () => ( { error: logErrorMock } ) )
 );
 
-const onHandlers = vi.hoisted( () => ( {} ) );
-const messageBusMock = vi.hoisted( () => ( {
+const mainOnHandlers = vi.hoisted( () => ( {} ) );
+const stepOnHandlers = vi.hoisted( () => ( {} ) );
+const mainEventBusMock = vi.hoisted( () => ( {
   on: vi.fn( ( eventType, handler ) => {
-    onHandlers[eventType] = handler;
+    mainOnHandlers[eventType] = handler;
+  } )
+} ) );
+const stepEventBusMock = vi.hoisted( () => ( {
+  emit: vi.fn( () => true ),
+  on: vi.fn( ( eventType, handler ) => {
+    stepOnHandlers[eventType] = handler;
   } )
 } ) );
 
 vi.mock( '#logger', () => ( { createChildLogger: createChildLoggerMock } ) );
-vi.mock( '#bus', () => ( { messageBus: messageBusMock } ) );
+vi.mock( '#bus', () => ( {
+  mainEventBus: mainEventBusMock,
+  stepEventBus: stepEventBusMock
+} ) );
 
 import {
+  emit,
   on,
   onActivityEnd,
   onActivityError,
@@ -27,6 +38,7 @@ import {
   onWorkflowError,
   onWorkflowStart
 } from './index.js';
+import { pendingHooks } from './pending_hooks.js';
 
 const workflowDetails = {
   workflowId: 'wf-1',
@@ -38,11 +50,6 @@ const workflowDetails = {
   attempt: 1
 };
 
-const catalogWorkflowDetails = {
-  ...workflowDetails,
-  workflowType: WORKFLOW_CATALOG
-};
-
 const activityInfo = {
   activityId: 'act-1',
   activityType: 'wf#step',
@@ -61,8 +68,12 @@ const aggregations = {
 describe( 'hooks/index', () => {
   beforeEach( () => {
     vi.clearAllMocks();
-    Object.keys( onHandlers ).forEach( k => {
-      delete onHandlers[k];
+    pendingHooks.clear();
+    Object.keys( mainOnHandlers ).forEach( k => {
+      delete mainOnHandlers[k];
+    } );
+    Object.keys( stepOnHandlers ).forEach( k => {
+      delete stepOnHandlers[k];
     } );
   } );
 
@@ -71,9 +82,9 @@ describe( 'hooks/index', () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       onError( handler );
 
-      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.ACTIVITY_ERROR, expect.any( Function ) );
-      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.WORKFLOW_ERROR, expect.any( Function ) );
-      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.RUNTIME_ERROR, expect.any( Function ) );
+      expect( mainEventBusMock.on ).toHaveBeenCalledWith( BusEventType.ACTIVITY_ERROR, expect.any( Function ) );
+      expect( mainEventBusMock.on ).toHaveBeenCalledWith( BusEventType.WORKFLOW_ERROR, expect.any( Function ) );
+      expect( mainEventBusMock.on ).toHaveBeenCalledWith( BusEventType.RUNTIME_ERROR, expect.any( Function ) );
     } );
 
     it( 'invokes handler with activity-shaped payload, forwarding bus fields', async () => {
@@ -81,7 +92,7 @@ describe( 'hooks/index', () => {
       onError( handler );
 
       const err = new Error( 'act-fail' );
-      await onHandlers[BusEventType.ACTIVITY_ERROR]( {
+      await mainOnHandlers[BusEventType.ACTIVITY_ERROR]( {
         eventId: 'evt-act-1',
         eventDate,
         activityInfo,
@@ -108,7 +119,7 @@ describe( 'hooks/index', () => {
       onError( handler );
 
       const err = new Error( 'wf-fail' );
-      await onHandlers[BusEventType.WORKFLOW_ERROR]( {
+      await mainOnHandlers[BusEventType.WORKFLOW_ERROR]( {
         eventId: 'evt-wf-1',
         eventDate,
         workflowDetails,
@@ -131,7 +142,7 @@ describe( 'hooks/index', () => {
       onError( handler );
 
       const error = new Error( 'rt' );
-      await onHandlers[BusEventType.RUNTIME_ERROR]( { eventId: 'evt-rt-1', eventDate, error } );
+      await mainOnHandlers[BusEventType.RUNTIME_ERROR]( { eventId: 'evt-rt-1', eventDate, error } );
 
       expect( handler ).toHaveBeenCalledWith( { eventId: 'evt-rt-1', eventDate, source: 'runtime', error } );
     } );
@@ -142,68 +153,52 @@ describe( 'hooks/index', () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       onBeforeWorkerStart( handler );
 
-      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.WORKER_BEFORE_START, expect.any( Function ) );
-      await onHandlers[BusEventType.WORKER_BEFORE_START]();
+      expect( mainEventBusMock.on ).toHaveBeenCalledWith( BusEventType.WORKER_BEFORE_START, expect.any( Function ) );
+      await mainOnHandlers[BusEventType.WORKER_BEFORE_START]();
 
       expect( handler ).toHaveBeenCalledWith( undefined );
     } );
   } );
 
-  describe( 'onWorkflowStart', () => {
-    it( 'skips catalog workflow and forwards bus fields for real workflows', async () => {
-      const handler = vi.fn().mockResolvedValue( undefined );
-      onWorkflowStart( handler );
-
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( {
-        eventId: 'evt-ignored', eventDate, workflowDetails: catalogWorkflowDetails
-      } ) );
-      expect( handler ).not.toHaveBeenCalled();
-
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( {
-        eventId: 'evt-start-1', eventDate, workflowDetails, extra: 'passthrough'
-      } ) );
-      expect( handler ).toHaveBeenCalledWith( {
-        eventId: 'evt-start-1', eventDate, workflowDetails, extra: 'passthrough'
-      } );
+  it( 'tracks a hook callback until it settles', async () => {
+    const deferred = { resolve: null };
+    const handlerPromise = new Promise( resolve => {
+      deferred.resolve = resolve;
     } );
-  } );
+    const handler = vi.fn( () => handlerPromise );
+    onActivityEnd( handler );
 
-  describe( 'onWorkflowEnd', () => {
-    it( 'skips catalog workflow and forwards bus fields for real workflows', async () => {
-      const handler = vi.fn().mockResolvedValue( undefined );
-      onWorkflowEnd( handler );
+    const callbackPromise = mainOnHandlers[BusEventType.ACTIVITY_END]( { activityInfo } );
 
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_END]( {
-        eventId: 'evt-ignored', eventDate, workflowDetails: catalogWorkflowDetails
-      } ) );
-      expect( handler ).not.toHaveBeenCalled();
+    expect( pendingHooks.size ).toBe( 1 );
 
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_END]( {
-        eventId: 'evt-end-1', eventDate, workflowDetails, extra: 'passthrough'
-      } ) );
-      expect( handler ).toHaveBeenCalledWith( {
-        eventId: 'evt-end-1', eventDate, workflowDetails, extra: 'passthrough'
-      } );
-    } );
+    deferred.resolve();
+    await callbackPromise;
+    expect( pendingHooks.size ).toBe( 0 );
   } );
 
-  describe( 'onWorkflowError', () => {
-    it( 'skips catalog workflow and forwards bus fields for real workflows', async () => {
+  describe( 'workflow lifecycle hooks', () => {
+    const cases = [
+      [ 'onWorkflowStart', onWorkflowStart, BusEventType.WORKFLOW_START, {} ],
+      [ 'onWorkflowEnd', onWorkflowEnd, BusEventType.WORKFLOW_END, {} ],
+      [ 'onWorkflowError', onWorkflowError, BusEventType.WORKFLOW_ERROR, { error: new Error( 'workflow failed' ) } ]
+    ];
+
+    it.each( cases )( '%s forwards bus fields', async ( _name, registerHook, eventType, extraFields ) => {
       const handler = vi.fn().mockResolvedValue( undefined );
-      const err = new Error( 'wf' );
-      onWorkflowError( handler );
+      const payload = {
+        eventId: 'evt-workflow-1',
+        eventDate,
+        workflowDetails,
+        extra: 'passthrough',
+        ...extraFields
+      };
+      registerHook( handler );
 
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_ERROR]( {
-        eventId: 'evt-ignored', eventDate, workflowDetails: catalogWorkflowDetails, error: err
-      } ) );
-      expect( handler ).not.toHaveBeenCalled();
+      expect( mainEventBusMock.on ).toHaveBeenCalledWith( eventType, expect.any( Function ) );
+      await mainOnHandlers[eventType]( payload );
 
-      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_ERROR]( {
-        eventId: 'evt-err-1', eventDate, workflowDetails, error: err, extra: 'passthrough'
-      } ) );
-      expect( handler ).toHaveBeenCalledWith( {
-        eventId: 'evt-err-1', eventDate, workflowDetails, error: err, extra: 'passthrough'
-      } );
+      expect( handler ).toHaveBeenCalledWith( payload );
     } );
   } );
 
@@ -214,53 +209,49 @@ describe( 'hooks/index', () => {
       [ 'onActivityError', onActivityError, BusEventType.ACTIVITY_ERROR, { error: new Error( 'activity failed' ) } ]
     ];
 
-    it.each( cases )( '%s skips internal activities and forwards bus fields', async ( _name, registerHook, eventType, extraFields = {} ) => {
+    it.each( cases )( '%s forwards internal activity bus fields', async ( _name, registerHook, eventType, extraFields = {} ) => {
       const handler = vi.fn().mockResolvedValue( undefined );
-      registerHook( handler );
-
-      expect( messageBusMock.on ).toHaveBeenCalledWith( eventType, expect.any( Function ) );
-
-      await Promise.resolve( onHandlers[eventType]( {
-        eventId: 'evt-ignored',
-        eventDate,
-        activityInfo,
-        workflowDetails,
-        outputActivityKind: ComponentType.INTERNAL_STEP,
-        ...extraFields
-      } ) );
-      expect( handler ).not.toHaveBeenCalled();
-
-      await Promise.resolve( onHandlers[eventType]( {
+      const payload = {
         eventId: 'evt-activity-1',
         eventDate,
         activityInfo,
         workflowDetails,
-        outputActivityKind: ComponentType.STEP,
+        outputActivityKind: 'internal_step',
         extra: 'passthrough',
         ...extraFields
-      } ) );
+      };
+      registerHook( handler );
 
-      expect( handler ).toHaveBeenCalledWith( {
-        eventId: 'evt-activity-1',
-        eventDate,
-        activityInfo,
-        workflowDetails,
-        outputActivityKind: ComponentType.STEP,
-        extra: 'passthrough',
-        ...extraFields
-      } );
+      expect( mainEventBusMock.on ).toHaveBeenCalledWith( eventType, expect.any( Function ) );
+      await mainOnHandlers[eventType]( payload );
+
+      expect( handler ).toHaveBeenCalledWith( payload );
     } );
   } );
 
   describe( 'on', () => {
-    it( 'subscribes to external event channel and forwards payload', async () => {
+    it( 'subscribes to SDK and user event channels and forwards payloads', async () => {
       const handler = vi.fn().mockResolvedValue( undefined );
       on( 'myEvent', handler );
 
-      expect( messageBusMock.on ).toHaveBeenCalledWith( 'external:myEvent', expect.any( Function ) );
-      await onHandlers['external:myEvent']( { foo: 1 } );
+      expect( stepEventBusMock.on ).toHaveBeenCalledWith( 'sdk:myEvent', expect.any( Function ) );
+      expect( stepEventBusMock.on ).toHaveBeenCalledWith( 'usr:myEvent', expect.any( Function ) );
+      await stepOnHandlers['sdk:myEvent']( { payload: { source: 'sdk' } } );
+      await stepOnHandlers['usr:myEvent']( { payload: { source: 'user' } } );
+
+      expect( handler ).toHaveBeenNthCalledWith( 1, { payload: { source: 'sdk' } } );
+      expect( handler ).toHaveBeenNthCalledWith( 2, { payload: { source: 'user' } } );
+    } );
+  } );
+
+  describe( 'emit', () => {
+    it( 'emits payloads on the user event channel', () => {
+      const payload = { foo: 1 };
+
+      const emitted = emit( 'myEvent', payload );
 
-      expect( handler ).toHaveBeenCalledWith( { foo: 1 } );
+      expect( stepEventBusMock.emit ).toHaveBeenCalledWith( 'usr:myEvent', payload );
+      expect( emitted ).toBe( true );
     } );
   } );
 } );

package/src/hooks/pending_hooks.js

@@ -0,0 +1,24 @@
+import { createChildLogger } from '#logger';
+
+export const pendingHooks = new Set();
+
+const log = createChildLogger( 'Hooks' );
+const flushTimeoutMs = 30_000;
+
+/**
+ * Await all pending hooks to flush for a certain time
+ */
+export const flushPendingHooks = async () => {
+  const state = { timeout: null };
+  try {
+    const flushed = await Promise.race( [
+      Promise.allSettled( [ ...pendingHooks ] ).then( _ => true ),
+      new Promise( r => state.timeout = setTimeout( () => r( false ), flushTimeoutMs ) )
+    ] );
+    if ( !flushed ) {
+      log.warn( 'Some hook callbacks exceeded the timeout and will not be awaited', { count: pendingHooks.size } );
+    }
+  } finally {
+    clearTimeout( state.timeout );
+  }
+};

package/src/hooks/pending_hooks.spec.js

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const logMock = vi.hoisted( () => ( { warn: vi.fn() } ) );
+
+vi.mock( '#logger', () => ( { createChildLogger: () => logMock } ) );
+
+import { flushPendingHooks, pendingHooks } from './pending_hooks.js';
+
+describe( 'pending hooks', () => {
+  beforeEach( () => {
+    pendingHooks.clear();
+    vi.clearAllMocks();
+  } );
+
+  afterEach( () => {
+    pendingHooks.clear();
+    vi.useRealTimers();
+  } );
+
+  it( 'waits for pending hooks to settle', async () => {
+    const deferred = { resolve: null };
+    const hookPromise = new Promise( resolve => {
+      deferred.resolve = resolve;
+    } );
+    pendingHooks.add( hookPromise );
+
+    const flushPromise = flushPendingHooks();
+    const state = { flushed: false };
+    flushPromise.then( () => {
+      state.flushed = true;
+    } );
+
+    await Promise.resolve();
+    expect( state.flushed ).toBe( false );
+
+    deferred.resolve();
+    await flushPromise;
+    expect( state.flushed ).toBe( true );
+  } );
+
+  it( 'stops waiting after the timeout', async () => {
+    vi.useFakeTimers();
+    pendingHooks.add( new Promise( () => {} ) );
+
+    const flushPromise = flushPendingHooks();
+    await vi.advanceTimersByTimeAsync( 30_000 );
+
+    await expect( flushPromise ).resolves.toBeUndefined();
+  } );
+
+  it( 'logs the number of hooks that exceeded the timeout', async () => {
+    vi.useFakeTimers();
+    pendingHooks.add( new Promise( () => {} ) );
+    pendingHooks.add( new Promise( () => {} ) );
+
+    const flushPromise = flushPendingHooks();
+    await vi.advanceTimersByTimeAsync( 30_000 );
+    await flushPromise;
+
+    expect( logMock.warn ).toHaveBeenCalledWith( expect.any( String ), { count: 2 } );
+  } );
+} );

package/src/interface/index.js

@@ -8,7 +8,7 @@ import {
 import { evaluator } from './evaluator.js';
 import { step } from './step.js';
 import { workflow } from './workflow.js';
-import { executeInParallel } from './workflow_utils.js';
+import { executeInParallel, hasErrorType } from './workflow_utils.js';
 import { sendHttpRequest, sendPostRequestAndAwaitWebhook } from './webhook.js';
 import { Logger } from './logger.js';
 
@@ -23,6 +23,7 @@ export {
   EvaluationVerdictResult,
   EvaluationFeedback,
   executeInParallel,
+  hasErrorType,
   sendHttpRequest,
   sendPostRequestAndAwaitWebhook
 };

package/src/interface/workflow_utils.d.ts

@@ -74,3 +74,18 @@ export declare function executeInParallel<T extends readonly ( () => Promise<unk
     onJobCompleted?: ( result: ParallelResults<T>[number] ) => void;
   }
 ): Promise<ParallelResults<T>>;
+
+/**
+ * Checks whether an error or any error in its cause chain matches an Error class.
+ *
+ * Temporal Application Failures are matched through their serialized `type`,
+ * in addition to standard `instanceof` and `name` checks.
+ *
+ * @param error - Error or failure chain to inspect
+ * @param ErrorType - Error class to match
+ * @returns Whether the Error class appears in the chain
+ */
+export declare function hasErrorType<T extends Error>(
+  error: unknown,
+  ErrorType: abstract new ( ...args: never[] ) => T
+): boolean;

package/src/interface/workflow_utils.js

@@ -48,3 +48,22 @@ export const executeInParallel = async ( { jobs, concurrency = Infinity, onJobCo
 
   return results.sort( ( a, b ) => a.index - b.index );
 };
+
+/**
+ * Check if an error, or any parts of its cause chain are instances of a given Error class.
+ * Also check .name and .type
+ *
+ * @param {Error} error
+ * @param {Error} ErrorType
+ * @returns {boolean}
+ */
+export const hasErrorType = ( error, ErrorType, depth = 0 ) => {
+  if ( depth > 20 || typeof ErrorType !== 'function' ) {
+    return false;
+  }
+  const expectedType = ErrorType.name;
+  if ( error instanceof ErrorType || error?.type === expectedType || error?.name === expectedType || error === expectedType ) {
+    return true;
+  }
+  return error?.cause ? hasErrorType( error.cause, ErrorType, depth + 1 ) : false;
+};

package/src/interface/workflow_utils.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { executeInParallel } from './workflow_utils.js';
+import { hasErrorType, executeInParallel } from './workflow_utils.js';
 
 describe( 'executeInParallel', () => {
   it( 'returns empty array for empty jobs', async () => {
@@ -188,3 +188,84 @@ describe( 'executeInParallel', () => {
     ] );
   } );
 } );
+
+describe( 'hasErrorType', () => {
+  class FooError extends Error {}
+
+  it( 'matches a direct error instance', () => {
+    expect( hasErrorType( new FooError( 'foo' ), FooError ) ).toBe( true );
+  } );
+
+  it( 'matches an error instance in the cause chain', () => {
+    const error = new Error( 'outer', {
+      cause: new Error( 'middle', {
+        cause: new FooError( 'foo' )
+      } )
+    } );
+
+    expect( hasErrorType( error, FooError ) ).toBe( true );
+  } );
+
+  it( 'matches Temporal ApplicationFailure type in the cause chain', () => {
+    const applicationFailure = Object.assign( new Error( 'foo' ), {
+      name: 'ApplicationFailure',
+      type: 'FooError'
+    } );
+    const activityFailure = Object.assign( new Error( 'Activity execution failed', {
+      cause: applicationFailure
+    } ), {
+      name: 'ActivityFailure'
+    } );
+
+    expect( hasErrorType( activityFailure, FooError ) ).toBe( true );
+  } );
+
+  it( 'matches a serialized error name', () => {
+    const error = Object.assign( new Error( 'foo' ), { name: 'FooError' } );
+
+    expect( hasErrorType( error, FooError ) ).toBe( true );
+  } );
+
+  it( 'matches an error serialized as its type name', () => {
+    expect( hasErrorType( 'FooError', FooError ) ).toBe( true );
+  } );
+
+  it( 'matches an error type in a plain object cause chain', () => {
+    const error = {
+      name: 'ActivityFailure',
+      cause: {
+        name: 'ApplicationFailure',
+        type: 'FooError'
+      }
+    };
+
+    expect( hasErrorType( error, FooError ) ).toBe( true );
+  } );
+
+  it.each( [ null, undefined, '', 42, false ] )( 'returns false for unsupported error value %j', error => {
+    expect( hasErrorType( error, FooError ) ).toBe( false );
+  } );
+
+  it( 'returns false when ErrorType is not a class', () => {
+    expect( hasErrorType( new FooError( 'foo' ), null ) ).toBe( false );
+  } );
+
+  it( 'returns false when the requested error type is absent', () => {
+    const error = new Error( 'outer', { cause: new TypeError( 'inner' ) } );
+
+    expect( hasErrorType( error, FooError ) ).toBe( false );
+  } );
+
+  it( 'keeps plain Error matching backwards compatible', () => {
+    expect( hasErrorType( new Error( 'foo' ), Error ) ).toBe( true );
+  } );
+
+  it( 'stops traversing cause chains after the depth limit', () => {
+    const createCauseChain = depth => depth === 20 ?
+      new FooError( 'foo' ) :
+      new Error( `depth-${depth}`, { cause: createCauseChain( depth + 1 ) } );
+    const root = new Error( 'root', { cause: createCauseChain( 0 ) } );
+
+    expect( hasErrorType( root, FooError ) ).toBe( false );
+  } );
+} );