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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.10.1-next.fc0a41f.0",
+  "version": "0.11.0",
   "description": "The core module of the output framework",
   "type": "module",
   "engines": {
@@ -22,6 +22,10 @@
     "./sdk/runtime": {
       "types": "./src/sdk/runtime/index.d.ts",
       "import": "./src/sdk/runtime/index.js"
+    },
+    "./temporal": {
+      "types": "./src/temporal/index.d.ts",
+      "import": "./src/temporal/index.js"
     }
   },
   "files": [
@@ -41,17 +45,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": {
@@ -74,6 +78,7 @@
     "#tracing": "./src/tracing/internal_interface.js",
     "#trace_attribute": "./src/tracing/trace_attribute.js",
     "#async_storage": "./src/async_storage.js",
+    "#temporal/*": "./src/temporal/*.js",
     "#internal_activities": "./src/internal_activities/index.js"
   },
   "scripts": {

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

package/src/helpers/error_serializer.js

@@ -0,0 +1,236 @@
+import { tryOrUndefined } from './function.js';
+import { redactUrl } from './redact.js';
+import { isUrl } from './string.js';
+
+const MAX_VALUE_DEPTH = 10;
+const MAX_PROTOTYPE_DEPTH = 10;
+const MAX_STRING_LEN = 16_384;
+const MAX_OBJECT_KEYS = 50;
+const MAX_OBJECT_KEY_LEN = 256;
+const MAX_ARRAY_SIZE = 50;
+const MAX_SERIALIZED_VALUES = 1000;
+const MAX_BIGINT = 10n ** BigInt( MAX_STRING_LEN - 1 ); // room for sign + trailing "n"
+const GLOBAL_IGNORED_KEYS = [
+  '__proto__',
+  // Raw Temporal wire failure; duplicates normalized causes/details and may contain encoded payloads.
+  'failure',
+  // Raw failure retained by Nexus for lossless round-tripping; duplicates surfaced diagnostics and internal payloads.
+  'originalFailure',
+  // Protobufjs reflection metadata; points into a large cyclic schema graph with no diagnostic value.
+  '$type',
+  // HTTP request/response
+  /^request$/i,
+  /^request_?body$/i,
+  /^request_?body_?values$/i,
+  /^response$/i,
+  // Headers
+  /^headers$/i,
+  /^request_?headers$/i,
+  /^response_?headers$/i,
+  // Credentials
+  /authorization$/i,
+  /authentication$/i,
+  /cookie$/i,
+  /key$/i,
+  /token$/i,
+  /password$/i,
+  /secret$/i,
+  /credentials?$/i
+];
+
+const Marker = {
+  BigIntTooLarge: '[BigInt too large]',
+  Circular: '[Circular Reference]',
+  MaxDepth: '[Maximum Depth Reached]',
+  MaxKeys: '[Maximum Object Properties Reached]',
+  MaxSelfCalls: '[Serialization Limit Reached]',
+  Unserializable: '[Unserializable]',
+  InvalidDate: '[Invalid Date]',
+  TruncatedArray: '... [:v more items omitted]',
+  TruncatedString: '... [:v more characters omitted]'
+};
+
+export const truncateString = ( v, max = MAX_STRING_LEN ) =>
+  v.length <= max ? v : ( v.slice( 0, max ) + Marker.TruncatedString.replace( ':v', v.length - max ) );
+
+export const truncateArray = ( v, max = MAX_ARRAY_SIZE ) =>
+  v.length <= max ? v : v.slice( 0, max ).concat( Marker.TruncatedArray.replace( ':v', v.length - max ) );
+
+/** Converts a prototype chain to a max sized array */
+export const flattenPrototypeChain = ( target, depth = 0, result = [], maxDepth = MAX_PROTOTYPE_DEPTH ) =>
+  !target || depth >= maxDepth ? result :
+    flattenPrototypeChain( Object.getPrototypeOf( target ), depth + 1, result.concat( target ), maxDepth );
+
+/**
+ * Define the best "name" for an Error object
+ * Rules: Assigned .name property > inherited .name if not "Error" > constructor.name
+ */
+export const resolveErrorName = target => {
+  // if its not error, don't return anything
+  if ( !( target instanceof Error ) ) {
+    return undefined;
+  }
+
+  const name = tryOrUndefined( () => target.name );
+  // if name is an explicit property return it
+  if ( Object.hasOwn( target, 'name' ) ) {
+    return name; // eslint-disable-line consistent-return
+  }
+
+  // if not explicit (resolves from parent) check if it not a default prop
+  if ( name !== undefined && name !== 'Error' ) {
+    return name; // eslint-disable-line consistent-return
+  }
+  // fallback to the constructor name, or undefined
+  return target.constructor?.name; // eslint-disable-line consistent-return
+};
+
+/** Check is target is in ancestor chain */
+const isAncestor = ( ancestor, target ) =>
+  ancestor !== null && ( ancestor.value === target || isAncestor( ancestor.ancestor, target ) );
+
+class GlobalCounter {
+  value = 0;
+  count() {
+    this.value++;
+    return this;
+  };
+}
+
+/** Recursive serialize a value, recursion comes for Array-like values and objects */
+const serializeValue = ( target, options, state = { depth: 0, seen: new GlobalCounter(), ancestor: null } ) => {
+  // If the same object was already seen in this branch, it is a circular reference
+  if ( isAncestor( state.ancestor, target ) ) {
+    return Marker.Circular;
+  }
+
+  // Reached the maximum times the function can self call
+  if ( state.seen.value >= MAX_SERIALIZED_VALUES ) {
+    return Marker.MaxSelfCalls;
+  }
+
+  // Depth control
+  if ( state.depth >= MAX_VALUE_DEPTH ) {
+    return Marker.MaxDepth;
+  }
+
+  const nextState = {
+    depth: state.depth + 1,
+    seen: state.seen.count(),
+    ancestor: { value: target, ancestor: state.ancestor }
+  };
+
+  try {
+    if ( target instanceof Date ) {
+      return Number.isNaN( target.getTime() ) ? Marker.InvalidDate : target.toISOString();
+    }
+
+    if ( target instanceof RegExp ) {
+      return target.toString();
+    }
+
+    if ( typeof target === 'bigint' ) {
+      return ( target >= MAX_BIGINT || target <= -MAX_BIGINT ) ? Marker.BigIntTooLarge : `${target}n`;
+    }
+
+    if ( typeof target === 'symbol' ) {
+      return truncateString( target.toString() );
+    }
+
+    if ( typeof target === 'function' ) {
+      return `[Function: ${target.name || '(anonymous)'}]`;
+    }
+
+    // Buffers, typed arrays, and raw ArrayBuffers
+    if ( ArrayBuffer.isView( target ) || target instanceof ArrayBuffer ) {
+      const sizeKey = target instanceof ArrayBuffer || target instanceof DataView ? 'byteLength' : 'length';
+      return `${target.constructor.name}(${target[sizeKey]})`;
+    }
+
+    if ( typeof target === 'string' ) {
+      return truncateString( isUrl( target ) ? redactUrl( target ) : target );
+    }
+
+    // Other primitives are returned as they are
+    if ( typeof target !== 'object' || target === null ) {
+      return target;
+    }
+
+    if ( target instanceof URL ) {
+      return truncateString( redactUrl( target ) );
+    }
+
+    // Maps/Sets use a helper function
+    if ( [ Map, Set ].some( I => target instanceof I ) ) {
+      const iterator = target instanceof Set ? target.values() : target.entries();
+      const values = iterator.take( MAX_ARRAY_SIZE ).toArray().map( v => serializeValue( v, options, nextState ) );
+      return values.concat( target.size > MAX_ARRAY_SIZE ? Marker.TruncatedArray.replace( ':v', target.size - MAX_ARRAY_SIZE ) : [] );
+    }
+
+    // Array as also recursively serialized
+    if ( Array.isArray( target ) ) {
+      return truncateArray( target ).map( value => serializeValue( value, options, nextState ) );
+    }
+
+    // Objects
+    const prototypes = flattenPrototypeChain( target );
+    const receiver = target;
+
+    const props = prototypes.reduce( ( projection, proto ) => {
+      if ( Object.keys( projection ).length > MAX_OBJECT_KEYS ) {
+        return projection;
+      }
+
+      const keys = Object.getOwnPropertyNames( proto );
+      for ( const key of keys ) {
+        if ( options.ignoredKeys.some( e => e.test ? e.test( key ) : e === key ) ) {
+          continue;
+        }
+
+        const sanitizedKey = truncateString( key, MAX_OBJECT_KEY_LEN );
+        if ( Object.hasOwn( projection, sanitizedKey ) ) { // do not overwrite similar keys
+          continue;
+        }
+
+        const value = tryOrUndefined( () => Reflect.get( proto, key, receiver ) );
+        if ( value === undefined || typeof value === 'function' ) {
+          continue;
+        }
+
+        // after confirming the key is valid, check if it would break the limit
+        if ( Object.keys( projection ).length === MAX_OBJECT_KEYS ) {
+          delete projection['...']; // make sure this is the last added property
+          return Object.assign( projection, { ['...']: Marker.MaxKeys } );
+        }
+
+        projection[sanitizedKey] = serializeValue( value, options, nextState );
+      };
+      return projection;
+    }, {} );
+
+    // name resolver
+    if ( !options.ignoredKeys.includes( 'name' ) && target instanceof Error ) {
+      const name = resolveErrorName( target );
+      if ( name !== undefined ) {
+        props.name = name;
+      }
+    }
+
+    return props;
+  } catch {
+    return Marker.Unserializable;
+  }
+};
+
+/**
+ * Converts an error-like value and its inherited properties into a plain object.
+ * Serializes recursively, including values inside Arrays, maps and sets.
+ * Has depth, prototype depth, max string size, max array/map/set size, max object props count limits.
+ *
+ * @param {*} target - Value to serialize
+ * @param {object} [options] - Serialization options
+ * @param {array} [options.dropKeys=[]] - Keys to exclude from the serialization (including recursion)
+ * @returns {*} Serialized value
+ */
+export const serializeError = ( target, { dropKeys } = {} ) =>
+  serializeValue( target, { ignoredKeys: GLOBAL_IGNORED_KEYS.concat( dropKeys ?? [] ) } );