@outputai/core 0.10.1-next.b7b2fbe.0 → 0.10.1-next.bf95a6f.0

package/src/interface/workflow_activity_options.js

@@ -1,5 +1,3 @@
-import { FatalError, ValidationError } from '#errors';
-
 export const defaultOptions = {
   activityOptions: {
     startToCloseTimeout: '20m',
@@ -9,8 +7,7 @@ export const defaultOptions = {
       backoffCoefficient: 2.0,
       maximumInterval: '2m',
       maximumAttempts: 3,
-      nonRetryableErrorTypes: [ ValidationError.name, FatalError.name ]
+      nonRetryableErrorTypes: []
     }
-  },
-  disableTrace: false
+  }
 };

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 );
+  } );
+} );

package/src/sdk/helpers/objects.d.ts

@@ -23,29 +23,34 @@ export declare const Objects: {
   isPlainObject( object: unknown ): boolean,
 
   /**
-   * Creates a new object by merging object `b` onto object `a`, biased toward `b`:
-   * - Fields in `b` overwrite fields in `a`.
-   * - Fields in `b` that don't exist in `a` are created.
-   * - Fields in `a` that don't exist in `b` are left unchanged.
-   *
-   * @param a - The base object.
-   * @param b - The overriding object.
-   * @throws {Error} If either `a` or `b` is not a plain object.
+   * Creates a new object by recursively merging overlays onto a base object.
+   * Later objects overwrite fields from earlier objects.
+   *
+   * Non-object overlays are ignored.
+   *
+   * @param base - The base object.
+   * @param overlays - The overriding objects, applied from left to right.
+   * @throws {Error} If `base` is not a plain object.
    * @returns A new merged object.
    */
-  deepMerge( a: object, b: object | null | undefined ): object,
+  deepMerge( base: object, ...overlays: Array<object | null | undefined> ): object,
 
   /**
-   * Creates a new object by merging object `b` onto object `a`, biased toward `b`:
-   * - Fields in `b` that don't exist in `a` are created.
-   * - Fields in `a` that don't exist in `b` are left unchanged.
-   * - Fields in `a` and `b` are passed as arguments to the resolve function (a,b) and its return assigns the new value.
-   *
-   * @param a - The base object.
-   * @param b - The overriding object.
-   * @param resolver - The resolver function.
-   * @throws {Error} If either `a` or `b` is not a plain object.
+   * Creates a new object by recursively merging overlays onto a base object.
+   * Existing leaf values are resolved by the resolver function.
+   *
+   * Non-object overlays are ignored.
+   *
+   * @param base - The base object.
+   * @param args - The overriding objects, applied from left to right, followed by the resolver function.
+   * @throws {Error} If `base` is not a plain object.
    * @returns A new merged object.
    */
-  deepMergeWithResolver( a: object, b: object | null | undefined, resolver: ( a: unknown, b: unknown ) => unknown ): object
+  deepMergeWithResolver(
+    base: object,
+    ...args: [
+      ...overlays: Array<object | null | undefined>,
+      resolver: ( a: unknown, b: unknown ) => unknown
+    ]
+  ): object
 };

package/src/sdk/runtime/events.d.ts

@@ -2,14 +2,12 @@
  * Tools to interact with Events
  */
 export declare const Event: {
+
   /**
-   * Emits a custom event on the in-process message bus.
-   *
-   * When called inside an Output activity context, the framework automatically
-   * attaches `activityInfo`, `workflowDetails`, and `outputActivityKind` onto the emitted payload.
+   * Emits an event on step message bus.
    *
    * @param eventName - The name of the event to emit
-   * @param payload - An optional payload to send to the event
+   * @param payload - An optional payload to send to the event.
    */
-  emit( eventName: string, payload?: object ): void;
+  emit( eventName: string, payload?: object ): boolean;
 };

package/src/sdk/runtime/events.js

@@ -1,18 +1,5 @@
-import { messageBus } from '#bus';
-import { Storage } from '#async_storage';
+import { stepEventBus } from '#bus';
 
 export const Event = {
-  emit: ( eventName, payload ) => {
-    const ctx = Storage.load();
-
-    messageBus.emit( `external:${eventName}`, {
-      ...payload ?? {},
-      ...( ctx && {
-        activityInfo: ctx.activityInfo,
-        workflowDetails: ctx.workflowDetails,
-        outputActivityKind: ctx.outputActivityKind
-      } )
-    } );
-  }
+  emit: ( eventName, payload ) => stepEventBus.emit( `sdk:${eventName}`, payload )
 };
-

package/src/sdk/runtime/events.spec.js

@@ -1,118 +1,40 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 
-const loadMock = vi.hoisted( () => vi.fn() );
 const emitMock = vi.hoisted( () => vi.fn() );
 
-vi.mock( '#async_storage', () => ( {
-  Storage: { load: loadMock }
-} ) );
-
 vi.mock( '#bus', () => ( {
-  messageBus: { emit: emitMock }
+  stepEventBus: { emit: emitMock }
 } ) );
 
 import { Event } from './events.js';
 
-// `eventId` stamping is the bus layer's responsibility (see bus.spec.js).
-// Assertions here use `objectContaining` so they don't have to know about that enrichment.
 describe( 'Event.emit', () => {
   beforeEach( () => {
     vi.clearAllMocks();
   } );
 
-  it( 'forwards activityInfo, workflowDetails, and outputActivityKind from storage', () => {
-    const activityInfo = {
-      activityId: 'act-1',
-      activityType: 'step',
-      workflowExecution: { workflowId: 'wf-1', runId: 'run-1' },
-      workflowType: 'workflow'
-    };
-    const workflowDetails = {
-      workflowId: 'wf-1',
-      runId: 'run-1',
-      workflowType: 'workflow'
-    };
-    loadMock.mockReturnValue( {
-      activityInfo,
-      workflowDetails,
-      outputActivityKind: 'step'
-    } );
+  it( 'forwards class instance payloads unchanged', () => {
+    class Payload {
+      value = 'test';
+    }
+    const payload = new Payload();
 
-    Event.emit( 'cost:llm:request', { modelId: 'gpt-4o' } );
+    Event.emit( 'test:event', payload );
 
-    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:llm:request', expect.objectContaining( {
-      activityInfo,
-      workflowDetails,
-      outputActivityKind: 'step',
-      modelId: 'gpt-4o'
-    } ) );
+    expect( emitMock ).toHaveBeenCalledWith( 'sdk:test:event', payload );
   } );
 
-  it( 'emits payload without context when storage is missing', () => {
-    loadMock.mockReturnValue( undefined );
+  it( 'emits plain object payloads on the SDK event channel', () => {
+    const payload = { modelId: 'gpt-4o' };
 
-    Event.emit( 'foo:bar', { x: 1 } );
+    Event.emit( 'cost:llm:request', payload );
 
-    expect( emitMock ).toHaveBeenCalledWith( 'external:foo:bar', { x: 1 } );
+    expect( emitMock ).toHaveBeenCalledWith( 'sdk:cost:llm:request', payload );
   } );
 
-  it( 'handles missing payload', () => {
-    const activityInfo = {
-      activityId: 'act-2',
-      activityType: 'step',
-      workflowExecution: { workflowId: 'wf-2', runId: 'run-2' },
-      workflowType: 'workflow'
-    };
-    const workflowDetails = {
-      workflowId: 'wf-2',
-      runId: 'run-2',
-      workflowType: 'workflow'
-    };
-    loadMock.mockReturnValue( {
-      activityInfo,
-      workflowDetails,
-      outputActivityKind: 'step'
-    } );
-
+  it( 'forwards a missing payload as undefined', () => {
     Event.emit( 'lifecycle:start' );
 
-    expect( emitMock ).toHaveBeenCalledWith( 'external:lifecycle:start', expect.objectContaining( {
-      activityInfo,
-      workflowDetails,
-      outputActivityKind: 'step'
-    } ) );
-  } );
-
-  it( 'does not let payload override activityInfo, workflowDetails, or outputActivityKind', () => {
-    const activityInfo = {
-      activityId: 'act-3',
-      activityType: 'step',
-      workflowExecution: { workflowId: 'wf-3', runId: 'run-3' },
-      workflowType: 'workflow'
-    };
-    const workflowDetails = {
-      workflowId: 'wf-3',
-      runId: 'run-3',
-      workflowType: 'workflow'
-    };
-    loadMock.mockReturnValue( {
-      activityInfo,
-      workflowDetails,
-      outputActivityKind: 'step'
-    } );
-
-    Event.emit( 'cost:http:request', {
-      activityInfo: { activityId: 'should-be-overridden' },
-      workflowDetails: { workflowId: 'should-be-overridden' },
-      outputActivityKind: 'should-be-overridden',
-      url: 'https://example.com'
-    } );
-
-    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:http:request', expect.objectContaining( {
-      activityInfo,
-      workflowDetails,
-      outputActivityKind: 'step',
-      url: 'https://example.com'
-    } ) );
+    expect( emitMock ).toHaveBeenCalledWith( 'sdk:lifecycle:start', undefined );
   } );
 } );

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 } );
   }
 };