@outputai/core 0.10.1-next.f6a7c1a.0 → 0.11.0

package/src/temporal/client.js

@@ -0,0 +1,47 @@
+import { Client } from '@temporalio/client';
+import { Storage } from '#async_storage';
+import { FatalError } from '#errors';
+
+// store the instance creation configs
+const config = {
+  connection: null,
+  namespace: null
+};
+
+// store a single instance that is created on demand
+const instance = {
+  client: null
+};
+
+// Adds the config necessary to init Clients
+export const setupClientConfig = ( { connection, namespace } ) => {
+  config.connection = new Proxy( connection, {
+    get( target, property, receiver ) {
+      if ( property === 'close' ) {
+        return async () => {
+          throw new FatalError( 'Client connection cannot be closed. It is owned by the worker.' );
+        };
+      }
+      return Reflect.get( target, property, receiver );
+    }
+  } );
+  config.namespace = namespace;
+};
+
+/** Return a new Temporal client instance */
+export const createTemporalClient = () => {
+  if ( !config.connection ) {
+    throw new FatalError( 'createTemporalClient() can only be called from within the worker runtime.' );
+  }
+  return new Client( { ...config } );
+};
+
+/** Get the workflow handle for the current workflow execution */
+export const getCurrentWorkflowHandle = () => {
+  const ctx = Storage.load();
+  if ( !ctx || !config.connection ) {
+    throw new FatalError( 'getCurrentWorkflowHandle() can only be called from Temporal activities running in the worker.' );
+  }
+  const { workflowId, runId } = ctx.activityInfo.workflowExecution;
+  return ( instance.client ??= new Client( config ) ).workflow.getHandle( workflowId, runId );
+};

package/src/temporal/client.spec.js

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const loadMock = vi.fn();
+vi.mock( '#async_storage', () => ( {
+  Storage: { load: loadMock }
+} ) );
+
+const getHandleMock = vi.fn();
+const clientConstructorMock = vi.fn( function () {
+  this.workflow = { getHandle: getHandleMock };
+} );
+vi.mock( '@temporalio/client', () => ( {
+  Client: clientConstructorMock
+} ) );
+
+const connection = {
+  fake: 'native-connection',
+  close: vi.fn().mockResolvedValue( undefined )
+};
+const activityContext = {
+  activityInfo: {
+    workflowExecution: {
+      workflowId: 'workflow-1',
+      runId: 'run-1'
+    }
+  }
+};
+
+describe( 'Temporal client', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    vi.resetModules();
+  } );
+
+  describe( 'createTemporalClient', () => {
+    it( 'throws a FatalError outside the worker runtime', async () => {
+      const { createTemporalClient } = await import( './client.js' );
+      const { FatalError } = await import( '#errors' );
+
+      expect( () => createTemporalClient() ).toThrow( FatalError );
+    } );
+
+    it( 'creates a client with the worker connection and namespace', async () => {
+      const { createTemporalClient, setupClientConfig } = await import( './client.js' );
+      setupClientConfig( { connection, namespace: 'namespace-1' } );
+
+      const client = createTemporalClient();
+
+      expect( clientConstructorMock ).toHaveBeenCalledWith( {
+        connection: expect.anything(),
+        namespace: 'namespace-1'
+      } );
+      expect( clientConstructorMock.mock.calls[0][0].connection ).not.toBe( connection );
+      expect( client ).toBeInstanceOf( clientConstructorMock );
+    } );
+
+    it( 'delegates connection access but prevents closing the worker connection', async () => {
+      const { createTemporalClient, setupClientConfig } = await import( './client.js' );
+      const { FatalError } = await import( '#errors' );
+      setupClientConfig( { connection, namespace: 'namespace-1' } );
+
+      createTemporalClient();
+      const clientConnection = clientConstructorMock.mock.calls[0][0].connection;
+
+      expect( clientConnection.fake ).toBe( 'native-connection' );
+      await expect( clientConnection.close() ).rejects.toThrow( FatalError );
+      expect( connection.close ).not.toHaveBeenCalled();
+    } );
+
+    it( 'returns a new client on each call', async () => {
+      const { createTemporalClient, setupClientConfig } = await import( './client.js' );
+      setupClientConfig( { connection, namespace: 'namespace-1' } );
+
+      expect( createTemporalClient() ).not.toBe( createTemporalClient() );
+      expect( clientConstructorMock ).toHaveBeenCalledTimes( 2 );
+    } );
+  } );
+
+  describe( 'getCurrentWorkflowHandle', () => {
+    it( 'throws a FatalError outside a Temporal activity context', async () => {
+      loadMock.mockReturnValue( undefined );
+      const { getCurrentWorkflowHandle, setupClientConfig } = await import( './client.js' );
+      const { FatalError } = await import( '#errors' );
+      setupClientConfig( { connection, namespace: 'namespace-1' } );
+
+      expect( () => getCurrentWorkflowHandle() ).toThrow( FatalError );
+    } );
+
+    it( 'throws a FatalError outside the worker runtime', async () => {
+      loadMock.mockReturnValue( activityContext );
+      const { getCurrentWorkflowHandle } = await import( './client.js' );
+      const { FatalError } = await import( '#errors' );
+
+      expect( () => getCurrentWorkflowHandle() ).toThrow( FatalError );
+    } );
+
+    it( 'returns the handle for the current workflow execution', async () => {
+      const handle = { signal: vi.fn() };
+      loadMock.mockReturnValue( activityContext );
+      getHandleMock.mockReturnValue( handle );
+      const { getCurrentWorkflowHandle, setupClientConfig } = await import( './client.js' );
+      setupClientConfig( { connection, namespace: 'namespace-1' } );
+
+      expect( getCurrentWorkflowHandle() ).toBe( handle );
+      expect( clientConstructorMock ).toHaveBeenCalledWith( {
+        connection: expect.anything(),
+        namespace: 'namespace-1'
+      } );
+      expect( getHandleMock ).toHaveBeenCalledWith( 'workflow-1', 'run-1' );
+    } );
+
+    it( 'reuses its client across calls', async () => {
+      loadMock.mockReturnValue( activityContext );
+      const { getCurrentWorkflowHandle, setupClientConfig } = await import( './client.js' );
+      setupClientConfig( { connection, namespace: 'namespace-1' } );
+
+      getCurrentWorkflowHandle();
+      getCurrentWorkflowHandle();
+
+      expect( clientConstructorMock ).toHaveBeenCalledTimes( 1 );
+      expect( getHandleMock ).toHaveBeenCalledTimes( 2 );
+    } );
+  } );
+} );

package/src/temporal/index.d.ts

@@ -0,0 +1,32 @@
+import type { Client, WorkflowHandle } from '@temporalio/client';
+
+/**
+ * Worker-side access to the Temporal layer.
+ *
+ * `createTemporalClient()` is available after the worker establishes its Temporal
+ * connection. `getCurrentWorkflowHandle()` is only available from Temporal Activities.
+ *
+ * > [!WARNING]
+ * > These are not Temporal sandbox safe, do not import in workflows directly.
+ * > These require the worker runtime, so in unit tests, mock the functions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Creates a Temporal [Client](https://typescript.temporal.io/api/classes/client.Client)
+ * instance with the same connection and namespace as the worker.
+ *
+ * @remarks
+ * - Only available after the worker establishes its Temporal connection.
+ */
+export declare const createTemporalClient: () => Client;
+
+/**
+ * Return the [WorkflowHandle](https://typescript.temporal.io/api/interfaces/client.WorkflowHandle)
+ * for the current workflow execution.
+ *
+ * @remarks
+ * - Only available from a Temporal Activity running in the worker.
+ */
+export declare const getCurrentWorkflowHandle: () => WorkflowHandle;

package/src/temporal/index.js

@@ -0,0 +1 @@
+export { createTemporalClient, getCurrentWorkflowHandle } from './client.js';

package/src/tracing/trace_engine.js

@@ -1,12 +1,13 @@
 import { Storage } from '#async_storage';
 import { EventEmitter } from 'node:events';
-import { serializeError } from './tools/utils.js';
+import { serializeError } from '#helpers/error_serializer';
 import { isStringboolTrue } from '#helpers/string';
 import * as localProcessor from './processors/local/index.js';
 import * as s3Processor from './processors/s3/index.js';
 import { createChildLogger } from '#logger';
 import { EventAction } from './trace_consts.js';
 import { BaseAttribute } from './trace_attribute.js';
+import { TransparentFatalError } from '#errors';
 
 const log = createChildLogger( 'Tracing' );
 
@@ -51,7 +52,7 @@ export const init = async () => {
       try {
         await p.exec( ...args );
       } catch ( error ) {
-        log.error( 'Processor execution error', { processor: p.name, error: error.message, stack: error.stack } );
+        log.error( 'Processor execution error', { processor: p.name, error: serializeError( error ) } );
       }
     } );
   }
@@ -87,15 +88,12 @@ export const addEventAction = ( action, { kind, name, id, parentId, details, tra
 export function addEventActionWithContext( action, options ) {
   const storeContent = Storage.load();
   if ( storeContent ) { // If there is no storageContext this was not called from a Temporal environment
-    const { parentId, traceInfo, addAttribute } = storeContent;
-    if ( action === EventAction.ADD_ATTR ) {
-      const attribute = options.details;
-      if ( !( attribute instanceof BaseAttribute ) ) {
-        throw new Error( `Event ${EventAction.ADD_ATTR} argument is not a BaseAttribute instance` );
-      } else {
-        addAttribute( options.details );
-      }
+    const { parentId, traceInfo } = storeContent;
+    if ( action === EventAction.ADD_ATTR && !( options.details instanceof BaseAttribute ) ) {
+      throw new Error( `Event ${EventAction.ADD_ATTR} argument is not a BaseAttribute instance` );
     }
-    addEventAction( action, { ...options, parentId, traceInfo } );
+    /** Unwraps Transparent error set in details so it behaves like in the interceptors */
+    const details = options.details instanceof TransparentFatalError ? options.details.cause : options.details;
+    addEventAction( action, { ...options, details, parentId, traceInfo } );
   }
 };

package/src/tracing/trace_engine.spec.js

@@ -5,10 +5,15 @@ vi.mock( '#async_storage', () => ( {
   Storage: { load: storageLoadMock }
 } ) );
 
-const logWarnMock = vi.fn();
+const serializeErrorMock = vi.fn( error => ( {
+  name: error.name,
+  message: error.message
+} ) );
+vi.mock( '#helpers/error_serializer', () => ( { serializeError: serializeErrorMock } ) );
+
 const logErrorMock = vi.fn();
 vi.mock( '#logger', () => ( {
-  createChildLogger: () => ( { warn: logWarnMock, error: logErrorMock } )
+  createChildLogger: () => ( { error: logErrorMock } )
 } ) );
 
 const localInitMock = vi.fn( async () => {} );
@@ -71,6 +76,24 @@ describe( 'tracing/trace_engine', () => {
     expect( payload.traceInfo ).toBe( traceInfo );
   } );
 
+  it( 'init() logs processor failures with serialized stacks', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+    const processorError = new Error( 'processor failed' );
+    localExecMock.mockRejectedValueOnce( processorError );
+    const { init, addEventAction } = await loadTraceEngine();
+    await init();
+
+    addEventAction( 'start', {
+      kind: 'step', name: 'N', id: '1', parentId: 'p', details: null, traceInfo
+    } );
+
+    await vi.waitFor( () => expect( logErrorMock ).toHaveBeenCalledWith( 'Processor execution error', {
+      processor: 'LOCAL',
+      error: { name: 'Error', message: 'processor failed' }
+    } ) );
+    expect( serializeErrorMock ).toHaveBeenCalledWith( processorError );
+  } );
+
   it( 'addEventAction() emits an entry consumed by processors', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = 'on';
     const { init, addEventAction } = await loadTraceEngine();
@@ -87,34 +110,34 @@ describe( 'tracing/trace_engine', () => {
     expect( payload.entry.details ).toBe( 'done' );
   } );
 
-  it( 'addEventAction() does not emit when traceInfo is absent', async () => {
-    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+  it( 'addEventAction() serializes error details before emitting', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = 'on';
     const { init, addEventAction } = await loadTraceEngine();
     await init();
+    const error = new TypeError( 'step failed' );
 
-    addEventAction( 'start', {
-      kind: 'step', name: 'X', id: '1', parentId: 'p', details: {},
-      traceInfo: undefined
+    addEventAction( 'error', {
+      kind: 'step', name: 'S', id: '3', parentId: 'p3', details: error,
+      traceInfo
+    } );
+
+    expect( serializeErrorMock ).toHaveBeenCalledWith( error );
+    expect( localExecMock.mock.calls[0][0].entry.details ).toEqual( {
+      name: 'TypeError',
+      message: 'step failed'
     } );
-    expect( localExecMock ).not.toHaveBeenCalled();
   } );
 
-  it( 'addEventAction() emits when kind is INTERNAL_STEP', async () => {
+  it( 'addEventAction() does not emit when traceInfo is absent', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = '1';
     const { init, addEventAction } = await loadTraceEngine();
     await init();
 
     addEventAction( 'start', {
-      kind: 'internal_step', name: 'Internal', id: '1', parentId: 'p', details: {},
-      traceInfo
-    } );
-    expect( localExecMock ).toHaveBeenCalledTimes( 1 );
-    expect( localExecMock.mock.calls[0][0].entry ).toMatchObject( {
-      kind: 'internal_step',
-      name: 'Internal',
-      id: '1',
-      parentId: 'p'
+      kind: 'step', name: 'X', id: '1', parentId: 'p', details: {},
+      traceInfo: undefined
     } );
+    expect( localExecMock ).not.toHaveBeenCalled();
   } );
 
   it( 'addEventActionWithContext() uses storage when available', async () => {
@@ -135,13 +158,34 @@ describe( 'tracing/trace_engine', () => {
     expect( payload.entry.action ).toBe( 'tick' );
   } );
 
-  it( 'addEventActionWithContext() records ADD_ATTR attributes through storage context', async () => {
+  it( 'addEventActionWithContext() unwraps transparent errors without mutating options', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = 'true';
-    const addAttributeMock = vi.fn();
     storageLoadMock.mockReturnValue( {
       parentId: 'ctx-p',
-      traceInfo,
-      addAttribute: addAttributeMock
+      traceInfo
+    } );
+    const { init, addEventActionWithContext } = await loadTraceEngine();
+    const { TransparentFatalError } = await import( '#errors' );
+    await init();
+
+    const cause = new TypeError( 'provider rejected request' );
+    const error = new TransparentFatalError( cause );
+    const options = { kind: 'llm', name: 'generate', id: 'llm-1', details: error };
+    addEventActionWithContext( 'error', options );
+
+    expect( options.details ).toBe( error );
+    expect( serializeErrorMock ).toHaveBeenCalledWith( cause );
+    expect( localExecMock.mock.calls[0][0].entry.details ).toEqual( {
+      name: 'TypeError',
+      message: 'provider rejected request'
+    } );
+  } );
+
+  it( 'addEventActionWithContext() emits validated ADD_ATTR trace entries', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = 'true';
+    storageLoadMock.mockReturnValue( {
+      parentId: 'ctx-p',
+      traceInfo
     } );
     const { init, addEventActionWithContext } = await loadTraceEngine();
     const { EventAction } = await import( './trace_consts.js' );
@@ -151,8 +195,6 @@ describe( 'tracing/trace_engine', () => {
     const attribute = new Attribute.HTTPRequestCount( 'https://example.test', 'req-1' );
     addEventActionWithContext( EventAction.ADD_ATTR, { kind: 'http', name: 'request', id: 'req-1', details: attribute } );
 
-    expect( addAttributeMock ).toHaveBeenCalledTimes( 1 );
-    expect( addAttributeMock ).toHaveBeenCalledWith( attribute );
     expect( localExecMock ).toHaveBeenCalledTimes( 1 );
     expect( localExecMock.mock.calls[0][0] ).toEqual( {
       traceInfo,
@@ -170,11 +212,9 @@ describe( 'tracing/trace_engine', () => {
 
   it( 'addEventActionWithContext() throws on invalid ADD_ATTR signal payloads', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = 'true';
-    const addAttributeMock = vi.fn();
     storageLoadMock.mockReturnValue( {
       parentId: 'ctx-p',
-      traceInfo,
-      addAttribute: addAttributeMock
+      traceInfo
     } );
     const { init, addEventActionWithContext } = await loadTraceEngine();
     const { EventAction } = await import( './trace_consts.js' );
@@ -186,7 +226,6 @@ describe( 'tracing/trace_engine', () => {
       { kind: 'http', name: 'request', id: 'req-1', details: invalidAttribute }
     ) ).toThrow( /not a BaseAttribute instance/ );
 
-    expect( addAttributeMock ).not.toHaveBeenCalled();
     expect( localExecMock ).not.toHaveBeenCalled();
   } );
 

package/src/worker/catalog_workflow/catalog_job.js

@@ -38,7 +38,7 @@ export class CatalogJob {
         throw e;
       }
       if ( !( e instanceof WorkflowNotFoundError ) ) {
-        log.warn( 'Error describing catalog workflow', { error: e } );
+        log.warn( 'Error describing catalog workflow', { error: e.message } );
       }
       return false;
     } );
@@ -52,7 +52,7 @@ export class CatalogJob {
         throw e;
       }
       if ( !( e instanceof WorkflowNotFoundError ) ) {
-        log.warn( 'Error describing catalog workflow', { error: e } );
+        log.warn( 'Error describing catalog workflow', { error: e.message } );
       }
       return false;
     } );
@@ -66,7 +66,7 @@ export class CatalogJob {
         throw e;
       }
       if ( !( e instanceof WorkflowNotFoundError ) ) {
-        log.warn( 'Error completing previous catalog workflow', { error: e } );
+        log.warn( 'Error completing previous catalog workflow', { error: e.message } );
       }
     } );
   };

package/src/worker/catalog_workflow/catalog_job.spec.js

@@ -121,7 +121,7 @@ describe( 'CatalogJob', () => {
 
     await job.run();
 
-    expect( mockLog.warn ).toHaveBeenCalledWith( 'Error completing previous catalog workflow', { error: completeError } );
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Error completing previous catalog workflow', { error: completeError.message } );
     expect( workflowStartMock ).toHaveBeenCalledWith( 'catalog', expect.any( Object ) );
     expect( job.error ).toBeNull();
   } );

package/src/worker/configs.js

@@ -36,8 +36,6 @@ const envVarSchema = z.object( {
   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 ) ),
-  // Time to allow for hooks to flush before shutdown
-  OUTPUT_PROCESS_FAILURE_SHUTDOWN_DELAY: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 3000 ) ),
   // Set temporal worker shutdown force time
   TEMPORAL_SHUTDOWN_FORCE_TIME: durationSchema,
   // Set temporal worker shutdown grace time
@@ -70,7 +68,6 @@ export const catalogId = envVars.OUTPUT_CATALOG_ID;
 export const workerTelemetryIntervalMs = envVars.OUTPUT_WORKER_TELEMETRY_INTERVAL_MS;
 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;
 export const shutdownForceTime = envVars.TEMPORAL_SHUTDOWN_FORCE_TIME;
 export const shutdownGraceTime = envVars.TEMPORAL_SHUTDOWN_GRACE_TIME;
 export const grpcProxy = envVars.TEMPORAL_GRPC_PROXY;

package/src/worker/index.js

@@ -12,13 +12,16 @@ import { initInterceptors } from './interceptors/index.js';
 import { createChildLogger } from '#logger';
 import { setupInterruptionHandler } from './interruption.js';
 import { CatalogJob } from './catalog_workflow/catalog_job.js';
-import { bootstrapFetchProxy } from './proxy.js';
 import { mainEventBus } from '#bus';
+import { flushPendingHooks } from '#hooks/pending_hooks';
 import { BusEventType } from '#consts';
 import { setupTelemetry } from './telemetry.js';
 import { TemporalConnectionMonitor } from './connection_monitor.js';
 import { bindGlobalFunctions } from './global_functions.js';
+import { setupClientConfig } from '#temporal/client';
 import { runOnce } from '#helpers/function';
+import { serializeError } from '#helpers/error_serializer';
+import { setupTemporalLogger } from './temporal_logger.js';
 
 import './log_hooks.js';
 
@@ -51,6 +54,9 @@ const state = {
 const callerDir = process.argv[2];
 
 const execute = async () => {
+  log.info( 'Setup Temporal Logger' );
+  setupTemporalLogger();
+
   log.info( 'Loading config...', { callerDir } );
   await loadHooks( callerDir );
 
@@ -61,7 +67,6 @@ const execute = async () => {
   const { activities } = await loadActivities( callerDir, workflows );
 
   mainEventBus.emit( BusEventType.WORKER_BEFORE_START );
-  bootstrapFetchProxy();
 
   log.info( 'Initializing tracing...' );
   await initTracing();
@@ -82,6 +87,9 @@ const execute = async () => {
 
   state.connection = await NativeConnection.connect( { address, tls: Boolean( apiKey ), apiKey, proxy } );
 
+  // add configs for the /temporal endpoint
+  setupClientConfig( { connection: state.connection, namespace } );
+
   log.info( 'Creating connection monitor...' );
   state.connectionMonitor = new TemporalConnectionMonitor( state.connection );
 
@@ -214,13 +222,18 @@ execute()
         .catch( e => log.warn( 'Connection close error', { error: e.message } ) );
     }
   } )
-  .then( () => log.info( 'Bye' ) )
-  .catch( error => {
-    log.error( 'Fatal error', { error: error.message, stack: error.stack } );
+  .then( async () => {
+    log.info( 'Flushing hook callbacks...' );
+    await flushPendingHooks();
+    log.info( 'Bye' );
+  } )
+  .catch( async error => {
+    log.error( 'Fatal error', { error: serializeError( error ) } );
 
     mainEventBus.emit( BusEventType.RUNTIME_ERROR, { error } );
 
-    const timeToFlushEvent = configs.processFailureShutdownDelay;
-    log.info( `Exiting in ${timeToFlushEvent}ms` );
-    setTimeout( () => process.exit( 1 ), timeToFlushEvent );
+    log.info( 'Flushing hook callbacks...' );
+    await flushPendingHooks();
+    log.info( 'Exiting...' );
+    setTimeout( () => process.exit( 1 ) );
   } );