@output.ai/core 0.5.7 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -15,6 +15,10 @@
     "./utils": {
       "types": "./src/utils/index.d.ts",
       "import": "./src/utils/index.js"
+    },
+    "./hooks": {
+      "types": "./src/hooks/index.d.ts",
+      "import": "./src/hooks/index.js"
     }
   },
   "files": [
@@ -48,6 +52,7 @@
     "access": "public"
   },
   "imports": {
+    "#bus": "./src/bus.js",
     "#consts": "./src/consts.js",
     "#errors": "./src/errors.js",
     "#logger": "./src/logger.js",

package/src/bus.js

@@ -0,0 +1,3 @@
+import { EventEmitter } from 'node:events';
+
+export const messageBus = new EventEmitter();

package/src/hooks/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Payload passed to the onError handler when a workflow, activity or runtime error occurs.
+ */
+export interface ErrorHookPayload {
+  /** 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. */
+  workflowName?: string;
+  /** Name of the activity, when the error is from an activity. */
+  activityName?: string;
+  /** The error thrown. */
+  error: Error;
+}
+
+/**
+ * Register a handler invoked on workflow, activity or runtime errors.
+ *
+ * @param handler - Function called with the error payload.
+ */
+export declare function onError( handler: ( payload: ErrorHookPayload ) => void ): void;

package/src/hooks/index.js

@@ -0,0 +1,21 @@
+import { messageBus } from '#bus';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Hooks' );
+
+export const onError = handler => {
+  const invokeHandler = async args => {
+    try {
+      await handler( args );
+    } catch ( error ) {
+      log.error( 'onError hook error', { error } );
+    }
+  };
+
+  messageBus.on( 'activity:error', async ( { workflowName, activityName, error } ) =>
+    invokeHandler( { source: 'activity', workflowName, activityName, error } ) );
+  messageBus.on( 'workflow:error', async ( { workflowName, error } ) =>
+    invokeHandler( { source: 'workflow', workflowName, error } ) );
+  messageBus.on( 'runtime:error', async ( { error } ) =>
+    invokeHandler( { source: 'runtime', error } ) );
+};

package/src/worker/configs.js

@@ -24,7 +24,9 @@ const envVarSchema = z.object( {
   // How often the worker sends a heartbeat to the Temporal Service during activity execution
   OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 2 * 60 * 1000 ) ), // 2min
   // Whether to send activity heartbeats (enabled by default)
-  OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: z.transform( v => v === undefined ? true : isStringboolTrue( v ) )
+  OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: z.transform( v => v === undefined ? true : isStringboolTrue( v ) ),
+  // Time to allow for hooks to flush before shutdown
+  OUTPUT_PROCESS_FAILURE_SHUTDOWN_DELAY: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 3000 ) )
 } );
 
 const { data: envVars, error } = envVarSchema.safeParse( process.env );
@@ -44,3 +46,4 @@ export const taskQueue = envVars.OUTPUT_CATALOG_ID;
 export const catalogId = envVars.OUTPUT_CATALOG_ID;
 export const activityHeartbeatIntervalMs = envVars.OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS;
 export const activityHeartbeatEnabled = envVars.OUTPUT_ACTIVITY_HEARTBEAT_ENABLED;
+export const processFailureShutdownDelay = envVars.OUTPUT_PROCESS_FAILURE_SHUTDOWN_DELAY;

package/src/worker/index.js

@@ -1,6 +1,6 @@
 import { Worker, NativeConnection } from '@temporalio/worker';
 import * as configs from './configs.js';
-import { loadActivities, loadWorkflows, createWorkflowsEntryPoint } from './loader.js';
+import { loadActivities, loadHooks, loadWorkflows, createWorkflowsEntryPoint } from './loader.js';
 import { sinks } from './sinks.js';
 import { createCatalog } from './catalog_workflow/index.js';
 import { init as initTracing } from '#tracing';
@@ -9,6 +9,7 @@ import { initInterceptors } from './interceptors.js';
 import { createChildLogger } from '#logger';
 import { registerShutdown } from './shutdown.js';
 import { startCatalog } from './start_catalog.js';
+import { messageBus } from '#bus';
 
 const log = createChildLogger( 'Worker' );
 
@@ -28,6 +29,9 @@ const callerDir = process.argv[2];
     maxConcurrentWorkflowTaskPolls
   } = configs;
 
+  log.info( 'Loading config...', { callerDir } );
+  await loadHooks( callerDir );
+
   log.info( 'Loading workflows...', { callerDir } );
   const workflows = await loadWorkflows( callerDir );
 
@@ -77,5 +81,7 @@ const callerDir = process.argv[2];
   process.exit( 0 );
 } )().catch( error => {
   log.error( 'Fatal error', { message: error.message, stack: error.stack } );
-  process.exit( 1 );
+  messageBus.emit( 'runtime:error', { error } );
+  log.info( `Exiting in ${configs.processFailureShutdownDelay}ms` );
+  setTimeout( () => process.exit( 1 ), configs.processFailureShutdownDelay );
 } );

package/src/worker/index.spec.js

@@ -17,16 +17,22 @@ const configValues = {
   maxConcurrentActivityTaskExecutions: 40,
   maxCachedWorkflows: 1000,
   maxConcurrentActivityTaskPolls: 5,
-  maxConcurrentWorkflowTaskPolls: 5
+  maxConcurrentWorkflowTaskPolls: 5,
+  processFailureShutdownDelay: 0
 };
 vi.mock( './configs.js', () => configValues );
 
+const messageBusMock = { on: vi.fn(), emit: vi.fn() };
+vi.mock( '#bus', () => ( { messageBus: messageBusMock } ) );
+
 const loadWorkflowsMock = vi.fn().mockResolvedValue( [] );
 const loadActivitiesMock = vi.fn().mockResolvedValue( {} );
+const loadHooksMock = vi.fn().mockResolvedValue( undefined );
 const createWorkflowsEntryPointMock = vi.fn().mockReturnValue( '/fake/workflows/path.js' );
 vi.mock( './loader.js', () => ( {
   loadWorkflows: loadWorkflowsMock,
   loadActivities: loadActivitiesMock,
+  loadHooks: loadHooksMock,
   createWorkflowsEntryPoint: createWorkflowsEntryPointMock
 } ) );
 
@@ -83,8 +89,9 @@ describe( 'worker/index', () => {
     import( './index.js' );
 
     await vi.waitFor( () => {
-      expect( loadWorkflowsMock ).toHaveBeenCalledWith( '/test/caller/dir' );
+      expect( loadHooksMock ).toHaveBeenCalledWith( '/test/caller/dir' );
     } );
+    expect( loadWorkflowsMock ).toHaveBeenCalledWith( '/test/caller/dir' );
     expect( loadActivitiesMock ).toHaveBeenCalledWith( '/test/caller/dir', [] );
     expect( createWorkflowsEntryPointMock ).toHaveBeenCalledWith( [] );
     expect( initTracing ).toHaveBeenCalled();
@@ -157,6 +164,8 @@ describe( 'worker/index', () => {
     await vi.waitFor( () => {
       expect( mockLog.error ).toHaveBeenCalledWith( 'Fatal error', expect.any( Object ) );
     } );
-    expect( exitMock ).toHaveBeenCalledWith( 1 );
+    await vi.waitFor( () => {
+      expect( exitMock ).toHaveBeenCalledWith( 1 );
+    } );
   } );
 } );

package/src/worker/interceptors/activity.js

@@ -5,6 +5,7 @@ import { headersToObject } from '../sandboxed_utils.js';
 import { LifecycleEvent, METADATA_ACCESS_SYMBOL } from '#consts';
 import { activityHeartbeatEnabled, activityHeartbeatIntervalMs } from '../configs.js';
 import { createChildLogger } from '#logger';
+import { messageBus } from '#bus';
 
 const log = createChildLogger( 'Activity' );
 /*
@@ -56,6 +57,8 @@ export class ActivityExecutionInterceptor {
         event: LifecycleEvent.ERROR, kind, ...logContext, durationMs: Date.now() - startDate, error: error.message
       } );
       addEventError( { details: error, ...traceArguments } );
+
+      messageBus.emit( 'activity:error', { error, workflowName, activityName: activityType } );
       throw error;
 
     } finally {

package/src/worker/loader.js

@@ -1,5 +1,5 @@
 import { dirname, join } from 'node:path';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { EOL } from 'node:os';
 import { fileURLToPath } from 'url';
 import { getTraceDestinations, sendHttpRequest } from '#internal_activities';
@@ -114,6 +114,24 @@ export async function loadWorkflows( rootDir ) {
   return workflows;
 };
 
+/**
+ * Loads the hook files from package.json's output config section.
+ *
+ * @param {string} rootDir
+ * @returns {void}
+ */
+export async function loadHooks( rootDir ) {
+  const packageFile = join( rootDir, 'package.json' );
+  if ( existsSync( packageFile ) ) {
+    const pkg = await import( packageFile, { with: { type: 'json' } } );
+    for ( const path of pkg.default.output?.hookFiles ?? [] ) {
+      const hookFile = join( rootDir, path );
+      await import( hookFile );
+      log.info( 'Hook file loaded', { path } );
+    }
+  }
+};
+
 /**
  * Creates a temporary index file importing all workflows for Temporal.
  *

package/src/worker/loader.spec.js

@@ -1,4 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
 
 vi.mock( '#consts', () => ( {
   ACTIVITY_SEND_HTTP_REQUEST: '__internal#sendHttpRequest',
@@ -22,11 +24,15 @@ vi.mock( './loader_tools.js', async importOriginal => {
   return { ...actual, importComponents: importComponentsMock };
 } );
 
-const mkdirSyncMock = vi.fn();
-const writeFileSyncMock = vi.fn();
+const fsMocks = vi.hoisted( () => ( {
+  mkdirSync: vi.fn(),
+  writeFileSync: vi.fn(),
+  existsSync: vi.fn().mockReturnValue( false )
+} ) );
 vi.mock( 'node:fs', () => ( {
-  mkdirSync: mkdirSyncMock,
-  writeFileSync: writeFileSyncMock
+  mkdirSync: fsMocks.mkdirSync,
+  writeFileSync: fsMocks.writeFileSync,
+  existsSync: fsMocks.existsSync
 } ) );
 
 describe( 'worker/loader', () => {
@@ -54,14 +60,14 @@ describe( 'worker/loader', () => {
     expect( activities['__internal#sendHttpRequest'] ).toBe( sendHttpRequestMock );
 
     // options file written with the collected activityOptions map
-    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
-    const [ writtenPath, contents ] = writeFileSyncMock.mock.calls[0];
+    expect( fsMocks.writeFileSync ).toHaveBeenCalledTimes( 1 );
+    const [ writtenPath, contents ] = fsMocks.writeFileSync.mock.calls[0];
     expect( writtenPath ).toMatch( /temp\/__activity_options\.js$/ );
     expect( contents ).toContain( 'export default' );
     expect( JSON.parse( contents.replace( /^export default\s*/, '' ).replace( /;\s*$/, '' ) ) ).toEqual( {
       'A#Act1': { retry: { maximumAttempts: 3 } }
     } );
-    expect( mkdirSyncMock ).toHaveBeenCalled();
+    expect( fsMocks.mkdirSync ).toHaveBeenCalled();
   } );
 
   it( 'loadActivities omits activity options when component has no options or no activityOptions', async () => {
@@ -74,7 +80,7 @@ describe( 'worker/loader', () => {
 
     await loadActivities( '/root', [ { name: 'A', path: '/a/workflow.js' } ] );
     const written = JSON.parse(
-      writeFileSyncMock.mock.calls[0][1].replace( /^export default\s*/, '' ).replace( /;\s*$/, '' )
+      fsMocks.writeFileSync.mock.calls[0][1].replace( /^export default\s*/, '' ).replace( /;\s*$/, '' )
     );
     expect( written['A#NoOptions'] ).toBeUndefined();
     expect( written['A#EmptyOptions'] ).toBeUndefined();
@@ -97,12 +103,12 @@ describe( 'worker/loader', () => {
     const workflows = [ { name: 'W', path: '/abs/wf.js' } ];
     const entry = createWorkflowsEntryPoint( workflows );
 
-    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
-    const [ writtenPath, contents ] = writeFileSyncMock.mock.calls[0];
+    expect( fsMocks.writeFileSync ).toHaveBeenCalledTimes( 1 );
+    const [ writtenPath, contents ] = fsMocks.writeFileSync.mock.calls[0];
     expect( entry ).toBe( writtenPath );
     expect( contents ).toContain( 'export { default as W } from \'/abs/wf.js\';' );
     expect( contents ).toContain( 'export { default as catalog }' );
-    expect( mkdirSyncMock ).toHaveBeenCalledTimes( 1 );
+    expect( fsMocks.mkdirSync ).toHaveBeenCalledTimes( 1 );
   } );
 
   it( 'loadActivities uses folder-based matchers for steps/evaluators and shared', async () => {
@@ -198,4 +204,33 @@ describe( 'worker/loader', () => {
     expect( activities['$shared#SharedEvalPrimary'] ).toBeTypeOf( 'function' );
     expect( activities['$shared#SharedEvalSecondary'] ).toBeTypeOf( 'function' );
   } );
+
+  describe( 'loadHooks', () => {
+    it( 'resolves without importing when package.json does not exist', async () => {
+      fsMocks.existsSync.mockReturnValue( false );
+      const { loadHooks } = await import( './loader.js' );
+      await expect( loadHooks( '/root' ) ).resolves.toBeUndefined();
+      expect( fsMocks.existsSync ).toHaveBeenCalledWith( join( '/root', 'package.json' ) );
+    } );
+
+    it( 'imports hook files listed in package.json output.hookFiles', async () => {
+      vi.doUnmock( 'node:fs' );
+      vi.resetModules();
+      const fs = await import( 'node:fs' );
+      const tmpDir = fs.mkdtempSync( join( tmpdir(), 'loader-spec-' ) );
+      try {
+        fs.writeFileSync( join( tmpDir, 'package.json' ), JSON.stringify( {
+          output: { hookFiles: [ 'hook.js' ] }
+        } ) );
+        fs.writeFileSync( join( tmpDir, 'hook.js' ), 'globalThis.__loadHooksTestLoaded = true;' );
+
+        const { loadHooks } = await import( './loader.js' );
+        await loadHooks( tmpDir );
+        expect( globalThis.__loadHooksTestLoaded ).toBe( true );
+      } finally {
+        delete globalThis.__loadHooksTestLoaded;
+        fs.rmSync( tmpDir, { recursive: true, force: true } );
+      }
+    } );
+  } );
 } );

package/src/worker/loader_tools.js

@@ -122,11 +122,11 @@ export const staticMatchers = {
    * @param {string} path - Path to test
    * @returns {boolean}
    */
-  sharedStepsDir: v => v.includes( `${sep}shared${sep}steps${sep}` ),
+  sharedStepsDir: v => v.includes( `${sep}shared${sep}steps${sep}` ) && v.endsWith( '.js' ),
   /**
    * Matches the shared folder for evaluators src/shared/evaluators/../evaluator_file.js
    * @param {string} path - Path to test
    * @returns {boolean}
    */
-  sharedEvaluatorsDir: v => v.includes( `${sep}shared${sep}evaluators${sep}` )
+  sharedEvaluatorsDir: v => v.includes( `${sep}shared${sep}evaluators${sep}` ) && v.endsWith( '.js' )
 };

package/src/worker/loader_tools.spec.js

@@ -1,7 +1,7 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { join, sep } from 'node:path';
-import { importComponents } from './loader_tools.js';
+import { importComponents, staticMatchers } from './loader_tools.js';
 
 describe( '.importComponents', () => {
   const TEMP_BASE = join( process.cwd(), 'sdk/core/temp_test_modules' );
@@ -116,3 +116,41 @@ describe( '.importComponents', () => {
     rmSync( root, { recursive: true, force: true } );
   } );
 } );
+
+describe( '.staticMatchers', () => {
+  describe( '.sharedStepsDir', () => {
+    it( 'matches .js files inside shared/steps/', () => {
+      expect( staticMatchers.sharedStepsDir( `${sep}app${sep}dist${sep}shared${sep}steps${sep}tools.js` ) ).toBe( true );
+    } );
+
+    it( 'matches .js files in nested subdirectories of shared/steps/', () => {
+      expect( staticMatchers.sharedStepsDir( `${sep}app${sep}dist${sep}shared${sep}steps${sep}utils${sep}helper.js` ) ).toBe( true );
+    } );
+
+    it( 'rejects .ts files inside shared/steps/', () => {
+      expect( staticMatchers.sharedStepsDir( `${sep}app${sep}src${sep}shared${sep}steps${sep}tools.ts` ) ).toBe( false );
+    } );
+
+    it( 'rejects non-.js files inside shared/steps/', () => {
+      expect( staticMatchers.sharedStepsDir( `${sep}app${sep}dist${sep}shared${sep}steps${sep}readme.md` ) ).toBe( false );
+    } );
+  } );
+
+  describe( '.sharedEvaluatorsDir', () => {
+    it( 'matches .js files inside shared/evaluators/', () => {
+      expect( staticMatchers.sharedEvaluatorsDir( `${sep}app${sep}dist${sep}shared${sep}evaluators${sep}quality.js` ) ).toBe( true );
+    } );
+
+    it( 'matches .js files in nested subdirectories of shared/evaluators/', () => {
+      expect( staticMatchers.sharedEvaluatorsDir( `${sep}app${sep}dist${sep}shared${sep}evaluators${sep}utils${sep}helper.js` ) ).toBe( true );
+    } );
+
+    it( 'rejects .ts files inside shared/evaluators/', () => {
+      expect( staticMatchers.sharedEvaluatorsDir( `${sep}app${sep}src${sep}shared${sep}evaluators${sep}quality.ts` ) ).toBe( false );
+    } );
+
+    it( 'rejects non-.js files inside shared/evaluators/', () => {
+      expect( staticMatchers.sharedEvaluatorsDir( `${sep}app${sep}dist${sep}shared${sep}evaluators${sep}readme.md` ) ).toBe( false );
+    } );
+  } );
+} );

package/src/worker/sinks.js

@@ -1,6 +1,7 @@
 import { LifecycleEvent, WORKFLOW_CATALOG } from '#consts';
 import { addEventStart, addEventEnd, addEventError } from '#tracing';
 import { createChildLogger } from '#logger';
+import { messageBus } from '#bus';
 
 const log = createChildLogger( 'Workflow' );
 
@@ -81,9 +82,10 @@ export const sinks = {
     },
 
     addWorkflowEventError: {
-      fn: ( workflowInfo, details ) => {
-        logWorkflowEvent( LifecycleEvent.ERROR, workflowInfo, details );
-        addWorkflowEvent( addEventError, workflowInfo, details );
+      fn: ( workflowInfo, error ) => {
+        logWorkflowEvent( LifecycleEvent.ERROR, workflowInfo, error );
+        addWorkflowEvent( addEventError, workflowInfo, error );
+        messageBus.emit( 'workflow:error', { error, workflowName: workflowInfo.workflowType } );
       },
       callDuringReplay: false
     },