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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.10.1-dev.b7b2fbe.0",
+  "version": "0.10.1-next.1070949.0",
   "description": "The core module of the output framework",
   "type": "module",
   "engines": {
@@ -41,17 +41,17 @@
     "@babel/parser": "7.29.2",
     "@babel/traverse": "7.29.0",
     "@babel/types": "7.29.0",
-    "@temporalio/activity": "1.17.0",
-    "@temporalio/client": "1.17.0",
-    "@temporalio/common": "1.17.0",
-    "@temporalio/worker": "1.17.0",
-    "@temporalio/workflow": "1.17.0",
+    "@temporalio/activity": "1.20.3",
+    "@temporalio/client": "1.20.3",
+    "@temporalio/common": "1.20.3",
+    "@temporalio/worker": "1.20.3",
+    "@temporalio/workflow": "1.20.3",
     "decimal.js": "10.6.0",
     "folder-hash": "4.1.3",
     "json-stream-stringify": "3.1.6",
     "redis": "5.12.1",
     "stacktrace-parser": "0.1.11",
-    "undici": "8.5.0",
+    "undici": "8.9.0",
     "winston": "3.19.0"
   },
   "peerDependencies": {
@@ -69,6 +69,7 @@
     "#consts": "./src/consts.js",
     "#errors": "./src/errors.js",
     "#logger": "./src/logger/index.js",
+    "#hooks/*": "./src/hooks/*.js",
     "#helpers/*": "./src/helpers/*.js",
     "#tracing": "./src/tracing/internal_interface.js",
     "#trace_attribute": "./src/tracing/trace_attribute.js",

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/consts.js

@@ -1,12 +1,11 @@
 export const ACTIVITY_GET_TRACE_DESTINATIONS = '__internal#getTraceDestinations';
 export const ACTIVITY_OPTIONS_FILENAME = '__activity_options.js';
 export const ACTIVITY_SEND_HTTP_REQUEST = '__internal#sendHttpRequest';
-export const ACTIVITY_WRAPPER_VERSION_FIELD = '__output_activity_wrapper_version';
 export const ACTIVITY_LOGGER_SYMBOL = Symbol.for( '__activity_logger' );
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const WORKFLOW_CATALOG = '$catalog';
+export const WORKFLOW_OPTIONS_FILENAME = '__workflow_options.js';
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
-export const WORKFLOW_WRAPPER_VERSION_FIELD = '__output_workflow_wrapper_version';
 
 export const INVOKE_ACTIVITY_SYMBOL = Symbol.for( '@outputai/core:__invoke_activity' );
 
@@ -42,3 +41,7 @@ export const BusEventType = {
 export const WorkflowSpecialOutput = {
   CONTINUED_AS_NEW: '<<continued_as_new>>'
 };
+
+export const ActivitySpecialOutput = {
+  ASYNC_HANDOFF: '<<async_handoff>>'
+};

package/src/errors.d.ts

@@ -3,7 +3,7 @@
  *
  * Throw this error to end the workflow execution altogether without retries.
  */
-export class FatalError extends Error { }
+export class FatalError extends Error {}
 
 /**
  * Error indicating invalid input or schema validation issues.
@@ -12,4 +12,14 @@ export class FatalError extends Error { }
  *
  * It will end the workflow execution without retries.
  */
-export class ValidationError extends Error { }
+export class ValidationError extends FatalError {}
+
+/**
+ * It serves to indicate a FatalError, but has no properties of its own, except cause.
+ *
+ * The SDK will discard it and use its cause in its place for logs, traces and the thrown error.
+ */
+export class TransparentFatalError extends FatalError {
+  readonly cause: Error;
+  constructor( cause: Error );
+}

package/src/errors.js

@@ -4,15 +4,29 @@
  */
 
 /**
- * Any generic fatal errors
+ * A FatalError breaks workflow execution
  */
 export class FatalError extends Error {
   name = 'FatalError';
 }
 
 /**
- * Any validation error
+ * It is a specialization of the FatalError to indicate validation problems
  */
-export class ValidationError extends Error {
+export class ValidationError extends FatalError {
   name = 'ValidationError';
 }
+
+/**
+ * It serves to indicate a FatalError, but has no properties of its own, except cause.
+ *
+ * The SDK will discard it and use its cause in its place for logs, traces and the thrown error.
+ */
+export class TransparentFatalError extends FatalError {
+  constructor( cause ) {
+    if ( !( cause instanceof Error ) ) {
+      throw new FatalError( 'TransparentFatalError argument must be an Error instance' );
+    }
+    super( undefined, { cause } );
+  }
+}

package/src/errors.spec.js

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { FatalError, TransparentFatalError, ValidationError } from './errors.js';
+
+describe( 'SDK errors', () => {
+  it( 'treats validation and transparent errors as fatal errors', () => {
+    const cause = new TypeError( 'provider rejected request' );
+    const transparentError = new TransparentFatalError( cause );
+
+    expect( new ValidationError( 'invalid input' ) ).toBeInstanceOf( FatalError );
+    expect( transparentError ).toBeInstanceOf( FatalError );
+    expect( transparentError.cause ).toBe( cause );
+  } );
+
+  it( 'rejects transparent errors without an Error cause', () => {
+    expect( () => new TransparentFatalError( 'provider rejected request' ) ).toThrow(
+      new FatalError( 'TransparentFatalError argument must be an Error instance' )
+    );
+  } );
+} );

package/src/helpers/activity_options.js

@@ -0,0 +1,21 @@
+import { FatalError } from '#errors';
+
+/**
+ * Returns a copy of activity options with framework-required policies enforced.
+ * @param {object} activityOptions
+ * @returns {object}
+ */
+export const enforceActivityOptions = activityOptions => {
+  const options = activityOptions ?? {};
+  const retry = options.retry ?? {};
+  const nonRetryableErrorTypes = retry.nonRetryableErrorTypes ?? [];
+  return {
+    ...options,
+    retry: {
+      ...retry,
+      nonRetryableErrorTypes: [
+        ...new Set( nonRetryableErrorTypes.concat( FatalError.name ) )
+      ]
+    }
+  };
+};

package/src/helpers/activity_options.spec.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { enforceActivityOptions } from './activity_options.js';
+
+describe( 'enforceActivityOptions', () => {
+  it( 'adds FatalError while preserving existing activity and retry options', () => {
+    const activityOptions = {
+      startToCloseTimeout: '5m',
+      retry: {
+        maximumAttempts: 4,
+        nonRetryableErrorTypes: [ 'DomainError' ]
+      }
+    };
+
+    expect( enforceActivityOptions( activityOptions ) ).toEqual( {
+      startToCloseTimeout: '5m',
+      retry: {
+        maximumAttempts: 4,
+        nonRetryableErrorTypes: [ 'DomainError', 'FatalError' ]
+      }
+    } );
+  } );
+
+  it( 'does not duplicate FatalError', () => {
+    const result = enforceActivityOptions( {
+      retry: { nonRetryableErrorTypes: [ 'FatalError', 'DomainError', 'FatalError' ] }
+    } );
+
+    expect( result.retry.nonRetryableErrorTypes ).toEqual( [ 'FatalError', 'DomainError' ] );
+  } );
+
+  it( 'returns a new object without mutating the provided options', () => {
+    const activityOptions = {
+      retry: {
+        maximumAttempts: 2,
+        nonRetryableErrorTypes: [ 'DomainError' ]
+      }
+    };
+    const result = enforceActivityOptions( activityOptions );
+
+    expect( result ).not.toBe( activityOptions );
+    expect( result.retry ).not.toBe( activityOptions.retry );
+    expect( activityOptions ).toEqual( {
+      retry: {
+        maximumAttempts: 2,
+        nonRetryableErrorTypes: [ 'DomainError' ]
+      }
+    } );
+  } );
+
+  it( 'creates required retry options when options are omitted', () => {
+    expect( enforceActivityOptions() ).toEqual( {
+      retry: { nonRetryableErrorTypes: [ 'FatalError' ] }
+    } );
+  } );
+} );