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

package/src/hooks/index.d.ts

@@ -79,25 +79,6 @@ export interface WorkflowDetails {
   attempt: number;
 }
 
-/**
- * Attribute totals collected while an activity executes.
- */
-export interface Aggregations {
-  /** Cost totals collected from HTTP request cost and LLM usage attributes. */
-  cost: {
-    total: number;
-  };
-  /** Token totals collected from LLM usage attributes. */
-  tokens: {
-    [tokenType: string]: number | undefined;
-    total: number;
-  };
-  /** HTTP request count totals. */
-  httpRequests: {
-    total: number;
-  };
-}
-
 /**
  * Common hook payload fields
  */
@@ -108,24 +89,6 @@ export interface HookPayloadBase {
   eventDate: number;
 }
 
-/**
- * Payload passed to the onError() handler when a workflow, activity or runtime error occurs.
- */
-export interface ErrorHookPayload extends HookPayloadBase {
-  /** Origin of the error: workflow execution, activity execution, or runtime. */
-  source: 'workflow' | 'activity' | 'runtime';
-  /** Information about the current workflow execution */
-  workflowDetails?: WorkflowDetails;
-  /** Temporal's activityInfo(). If source is activity */
-  activityInfo?: Info;
-  /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
-  outputActivityKind: string;
-  /** Attribute totals collected during the activity execution. */
-  aggregations?: Aggregations | null;
-  /** The error thrown. */
-  error: Error;
-}
-
 /**
  * Common hook payload fields for events associated with an workflow.
  */
@@ -148,7 +111,13 @@ export type WorkflowEndHookPayload = WorkflowPayloadBase;
  * Payload passed to the onWorkflowError() handler when a workflow run fails.
  */
 export interface WorkflowErrorHookPayload extends WorkflowPayloadBase {
-  /** The error thrown. */
+  /**
+   * Workflow error rehydrated after crossing the Temporal sandbox boundary.
+   * Preserves `name`, `message`, `cause`, and other enumerable properties from
+   * the serialized form; it is a reconstructed `Error`, not the original class.
+   * Extra fields are present at runtime but not on the `Error` type — narrow or
+   * cast in TypeScript when you need them.
+   */
   error: Error;
 }
 
@@ -172,21 +141,43 @@ export type ActivityStartHookPayload = ActivityPayloadBase;
 /**
  * Payload passed to the onActivityEnd() handler when an activity completes successfully.
  */
-export interface ActivityEndHookPayload extends ActivityPayloadBase {
-  /** Attribute totals collected during the activity execution. */
-  aggregations: Aggregations | null;
-}
+export type ActivityEndHookPayload = ActivityPayloadBase;
 
 /**
  * Payload passed to the onActivityError() handler when an activity fails.
  */
 export interface ActivityErrorHookPayload extends ActivityPayloadBase {
-  /** Attribute totals collected during the activity execution. */
-  aggregations: Aggregations | null;
   /** The error thrown. */
   error: Error;
 }
 
+/**
+ * Payload passed to the onError() handler when a workflow, activity or runtime error occurs.
+ */
+export type ErrorHookPayload =
+  ( WorkflowPayloadBase & {
+    /** Workflow error origin. */
+    source: 'workflow';
+    /**
+     * Workflow error rehydrated after crossing the Temporal sandbox boundary.
+     * Preserves `name`, `message`, `cause`, and other enumerable properties from
+     * the serialized form; it is a reconstructed `Error`, not the original class.
+     * Extra fields are present at runtime but not on the `Error` type — narrow or
+     * cast in TypeScript when you need them.
+     */
+    error: Error;
+  } ) |
+  ( ActivityErrorHookPayload & {
+    /** Activity error origin. */
+    source: 'activity';
+  } ) |
+  ( HookPayloadBase & {
+    /** Worker runtime error origin. */
+    source: 'runtime';
+    /** The original error instance. */
+    error: Error;
+  } );
+
 /**
  * Register a handler to be invoked on workflow, activity or runtime errors.
  *

package/src/hooks/index.js

@@ -1,5 +1,6 @@
 import { mainEventBus, stepEventBus } from '#bus';
 import { BusEventType } from '#consts';
+import { serializeError } from '#helpers/error_serializer';
 import { createChildLogger } from '#logger';
 import { pendingHooks } from './pending_hooks.js';
 
@@ -15,7 +16,7 @@ const log = createChildLogger( 'Hooks' );
 const callHookCb = ( fn, args, hookName ) => {
   const promise = Promise.resolve()
     .then( () => fn( args ) )
-    .catch( e => log.error( `${hookName} hook error`, { message: e.message, stack: e.stack } ) )
+    .catch( e => log.error( `${hookName} hook error`, { error: serializeError( e ) } ) )
     .finally( () => pendingHooks.delete( promise ) );
   pendingHooks.add( promise );
   return promise;

package/src/hooks/index.spec.js

@@ -5,6 +5,11 @@ const logErrorMock = vi.hoisted( () => vi.fn() );
 const createChildLoggerMock = vi.hoisted( () =>
   vi.fn( () => ( { error: logErrorMock } ) )
 );
+const serializeErrorMock = vi.hoisted( () => vi.fn( error => ( {
+  name: error.name,
+  message: error.message,
+  stack: error.stack
+} ) ) );
 
 const mainOnHandlers = vi.hoisted( () => ( {} ) );
 const stepOnHandlers = vi.hoisted( () => ( {} ) );
@@ -21,6 +26,7 @@ const stepEventBusMock = vi.hoisted( () => ( {
 } ) );
 
 vi.mock( '#logger', () => ( { createChildLogger: createChildLoggerMock } ) );
+vi.mock( '#helpers/error_serializer', () => ( { serializeError: serializeErrorMock } ) );
 vi.mock( '#bus', () => ( {
   mainEventBus: mainEventBusMock,
   stepEventBus: stepEventBusMock
@@ -59,12 +65,6 @@ const activityInfo = {
 
 const eventDate = 1710000001234;
 
-const aggregations = {
-  cost: { total: 0 },
-  tokens: { total: 0 },
-  httpRequests: { total: 1 }
-};
-
 describe( 'hooks/index', () => {
   beforeEach( () => {
     vi.clearAllMocks();
@@ -145,6 +145,14 @@ describe( 'hooks/index', () => {
       await mainOnHandlers[BusEventType.RUNTIME_ERROR]( { eventId: 'evt-rt-1', eventDate, error } );
 
       expect( handler ).toHaveBeenCalledWith( { eventId: 'evt-rt-1', eventDate, source: 'runtime', error } );
+      expect( logErrorMock ).toHaveBeenCalledWith( 'onError hook error', {
+        error: {
+          name: 'Error',
+          message: 'boom',
+          stack: expect.any( String )
+        }
+      } );
+      expect( serializeErrorMock ).toHaveBeenCalledWith( expect.objectContaining( { message: 'boom' } ) );
     } );
   } );
 
@@ -205,7 +213,7 @@ describe( 'hooks/index', () => {
   describe( 'activity lifecycle hooks', () => {
     const cases = [
       [ 'onActivityStart', onActivityStart, BusEventType.ACTIVITY_START, undefined ],
-      [ 'onActivityEnd', onActivityEnd, BusEventType.ACTIVITY_END, { aggregations } ],
+      [ 'onActivityEnd', onActivityEnd, BusEventType.ACTIVITY_END ],
       [ 'onActivityError', onActivityError, BusEventType.ACTIVITY_ERROR, { error: new Error( 'activity failed' ) } ]
     ];
 

package/src/interface/evaluator.d.ts

@@ -16,7 +16,7 @@ export type EvaluatorOptions = {
 /**
  * The handler function of an evaluator.
  *
- * @param input - The evaluator input; it matches the schema defined by `inputSchema`.
+ * @param input - Parsed evaluator input (`z.infer<inputSchema>`).
  *
  * @returns The result of the evaluation.
  */
@@ -30,14 +30,15 @@ export type EvaluatorFunction<
 /**
  * A wrapper around the user defined `fn` handler function.
  *
- * It has the same signature and returns the same value, calling the user function inside.
- *
- * It adds input validation based on the `inputSchema`.
+ * Callers pass values accepted by `inputSchema` (`z.input`). The wrapper parses input
+ * and invokes `fn`.
  */
-export type EvaluatorFunctionWrapper<EvaluatorFunction extends ( ...args: any ) => any> = // eslint-disable-line @typescript-eslint/no-explicit-any
-  Parameters<EvaluatorFunction> extends [infer Input] ?
-    ( input: Input ) => ReturnType<EvaluatorFunction> :
-    () => ReturnType<EvaluatorFunction>;
+export type EvaluatorFunctionWrapper<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  Result extends EvaluationResult = EvaluationResult
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.input<InputSchema> ) => Promise<Result> :
+  () => Promise<Result>;
 
 /**
  * Creates an evaluation function. It is similar to a step, but must return an EvaluationResult.
@@ -67,4 +68,4 @@ export declare function evaluator<
   inputSchema: InputSchema;
   fn: EvaluatorFunction<InputSchema, Result>;
   options?: EvaluatorOptions;
-} ): EvaluatorFunctionWrapper<EvaluatorFunction<InputSchema, Result>>;
+} ): EvaluatorFunctionWrapper<InputSchema, Result>;

package/src/interface/evaluator.js

@@ -13,11 +13,6 @@ export function evaluator( { name, description, inputSchema, fn, options } ) {
     description,
     inputSchema,
     options,
-    handler: async input => {
-      validator.validateInput( input );
-      const output = await fn( input );
-      validator.validateOutput( output );
-      return output;
-    }
+    handler: async input => validator.parseOutput( await fn( validator.parseInput( input ) ) )
   } );
 }

package/src/interface/evaluator.spec.js

@@ -9,8 +9,8 @@ import {
 import { ValidationError } from '#errors';
 
 const validateDefinitionMock = vi.hoisted( () => vi.fn() );
-const validateInputMock = vi.hoisted( () => vi.fn() );
-const validateOutputMock = vi.hoisted( () => vi.fn() );
+const parseInputMock = vi.hoisted( () => vi.fn( input => input ) );
+const parseOutputMock = vi.hoisted( () => vi.fn( output => output ) );
 const validatorConstructorMock = vi.hoisted( () => vi.fn() );
 const createEvaluatorMock = vi.hoisted( () => vi.fn( ( { handler } ) => handler ) );
 
@@ -22,8 +22,8 @@ vi.mock( './validations/index.js', () => {
 
     constructor( ...args ) {
       validatorConstructorMock( ...args );
-      this.validateInput = validateInputMock;
-      this.validateOutput = validateOutputMock;
+      this.parseInput = parseInputMock;
+      this.parseOutput = parseOutputMock;
     }
   }
 
@@ -87,15 +87,15 @@ describe( 'evaluator()', () => {
 
     await expect( wrapper( { value: 'input' } ) ).resolves.toBe( output );
 
-    expect( validateInputMock ).toHaveBeenCalledWith( { value: 'input' } );
+    expect( parseInputMock ).toHaveBeenCalledWith( { value: 'input' } );
     expect( fn ).toHaveBeenCalledWith( { value: 'input' } );
-    expect( validateOutputMock ).toHaveBeenCalledWith( output );
+    expect( parseOutputMock ).toHaveBeenCalledWith( output );
   } );
 
   it( 'does not call the evaluator function when input validation throws', async () => {
     const { evaluator } = await import( './evaluator.js' );
     const error = new ValidationError( 'invalid input' );
-    validateInputMock.mockImplementationOnce( () => {
+    parseInputMock.mockImplementationOnce( () => {
       throw error;
     } );
     const fn = vi.fn();
@@ -106,13 +106,13 @@ describe( 'evaluator()', () => {
 
     await expect( wrapper( { value: 'bad' } ) ).rejects.toBe( error );
     expect( fn ).not.toHaveBeenCalled();
-    expect( validateOutputMock ).not.toHaveBeenCalled();
+    expect( parseOutputMock ).not.toHaveBeenCalled();
   } );
 
   it( 'propagates output validation errors after the evaluator function runs', async () => {
     const { evaluator } = await import( './evaluator.js' );
     const error = new ValidationError( 'invalid output' );
-    validateOutputMock.mockImplementationOnce( () => {
+    parseOutputMock.mockImplementationOnce( () => {
       throw error;
     } );
     const output = { value: 'not-an-evaluation-result' };
@@ -124,7 +124,7 @@ describe( 'evaluator()', () => {
 
     await expect( wrapper( { value: 'input' } ) ).rejects.toBe( error );
     expect( fn ).toHaveBeenCalledOnce();
-    expect( validateOutputMock ).toHaveBeenCalledWith( output );
+    expect( parseOutputMock ).toHaveBeenCalledWith( output );
   } );
 } );
 

package/src/interface/step.d.ts

@@ -15,31 +15,32 @@ export type StepOptions = {
 /**
  * The handler function of a step.
  *
- * @param input - The step input; it matches the schema defined by `inputSchema`.
+ * @param input - Parsed step input (`z.infer<inputSchema>`).
  *
- * @returns A value matching the schema defined by `outputSchema`.
+ * @returns A value accepted by `outputSchema` before parse (`z.input<outputSchema>`).
  */
 export type StepFunction<
   InputSchema extends AnyZodSchema | undefined = undefined,
   OutputSchema extends AnyZodSchema | undefined = undefined
 > = InputSchema extends AnyZodSchema ?
-  ( input: z.infer<InputSchema> ) => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
-  () => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
+  ( input: z.infer<InputSchema> ) => Promise<OutputSchema extends AnyZodSchema ? z.input<OutputSchema> : void> :
+  () => Promise<OutputSchema extends AnyZodSchema ? z.input<OutputSchema> : void>;
 
 /**
  * A wrapper around the user defined `fn` handler function.
  *
- * It accepts the same input and returns the same value, calling the user function inside.
- *
- * It adds input and output validation based on the `inputSchema`, `outputSchema`.
+ * Callers pass values accepted by `inputSchema` (`z.input`). The wrapper parses input,
+ * invokes `fn`, parses output, and returns `z.infer<outputSchema>`.
  *
- * @param input - The Step input; it matches the schema defined by `inputSchema`.
- * @returns A value matching the schema defined by `outputSchema`.
+ * @param input - The step input before `inputSchema` parse.
+ * @returns The step output after `outputSchema` parse.
  */
-export type StepFunctionWrapper<StepFunction extends ( ...args: any ) => any> = // eslint-disable-line @typescript-eslint/no-explicit-any
-  Parameters<StepFunction> extends [infer Input] ?
-    ( input: Input ) => ReturnType<StepFunction> :
-    () => ReturnType<StepFunction>;
+export type StepFunctionWrapper<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.input<InputSchema> ) => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
+  () => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
 
 /**
  * Creates a step.
@@ -123,7 +124,7 @@ export type StepFunctionWrapper<StepFunction extends ( ...args: any ) => any> =
  * @param params.outputSchema - Zod schema for the `fn` output
  * @param params.fn - A handler function containing the step code
  * @param params.options - Optional step options.
- * @returns The same handler function set at `fn`
+ * @returns A wrapper that parses input/output around `fn`
  */
 export declare function step<
   InputSchema extends AnyZodSchema | undefined = undefined,
@@ -135,4 +136,4 @@ export declare function step<
   outputSchema?: OutputSchema;
   fn: StepFunction<InputSchema, OutputSchema>;
   options?: StepOptions;
-} ): StepFunctionWrapper<StepFunction<InputSchema, OutputSchema>>;
+} ): StepFunctionWrapper<InputSchema, OutputSchema>;

package/src/interface/step.js

@@ -14,11 +14,6 @@ export function step( { name, description, inputSchema, outputSchema, fn, option
     inputSchema,
     outputSchema,
     options,
-    handler: async input => {
-      validator.validateInput( input );
-      const output = await fn( input );
-      validator.validateOutput( output );
-      return output;
-    }
+    handler: async input => validator.parseOutput( await fn( validator.parseInput( input ) ) )
   } );
 }

package/src/interface/step.spec.js

@@ -2,8 +2,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ValidationError } from '#errors';
 
 const validateDefinitionMock = vi.hoisted( () => vi.fn() );
-const validateInputMock = vi.hoisted( () => vi.fn() );
-const validateOutputMock = vi.hoisted( () => vi.fn() );
+const parseInputMock = vi.hoisted( () => vi.fn( input => input ) );
+const parseOutputMock = vi.hoisted( () => vi.fn( output => output ) );
 const validatorConstructorMock = vi.hoisted( () => vi.fn() );
 const createStepMock = vi.hoisted( () => vi.fn( ( { handler } ) => handler ) );
 
@@ -15,8 +15,8 @@ vi.mock( './validations/index.js', () => {
 
     constructor( ...args ) {
       validatorConstructorMock( ...args );
-      this.validateInput = validateInputMock;
-      this.validateOutput = validateOutputMock;
+      this.parseInput = parseInputMock;
+      this.parseOutput = parseOutputMock;
     }
   }
 
@@ -86,15 +86,15 @@ describe( 'step()', () => {
 
     await expect( wrapper( { value: 'input' } ) ).resolves.toBe( output );
 
-    expect( validateInputMock ).toHaveBeenCalledWith( { value: 'input' } );
+    expect( parseInputMock ).toHaveBeenCalledWith( { value: 'input' } );
     expect( fn ).toHaveBeenCalledWith( { value: 'input' } );
-    expect( validateOutputMock ).toHaveBeenCalledWith( output );
+    expect( parseOutputMock ).toHaveBeenCalledWith( output );
   } );
 
   it( 'does not call the step function when input validation throws', async () => {
     const { step } = await import( './step.js' );
     const error = new ValidationError( 'invalid input' );
-    validateInputMock.mockImplementationOnce( () => {
+    parseInputMock.mockImplementationOnce( () => {
       throw error;
     } );
     const fn = vi.fn();
@@ -105,13 +105,13 @@ describe( 'step()', () => {
 
     await expect( wrapper( { value: 'bad' } ) ).rejects.toBe( error );
     expect( fn ).not.toHaveBeenCalled();
-    expect( validateOutputMock ).not.toHaveBeenCalled();
+    expect( parseOutputMock ).not.toHaveBeenCalled();
   } );
 
   it( 'propagates output validation errors after the step function runs', async () => {
     const { step } = await import( './step.js' );
     const error = new ValidationError( 'invalid output' );
-    validateOutputMock.mockImplementationOnce( () => {
+    parseOutputMock.mockImplementationOnce( () => {
       throw error;
     } );
     const output = { ok: false };
@@ -123,6 +123,6 @@ describe( 'step()', () => {
 
     await expect( wrapper( { value: 'input' } ) ).rejects.toBe( error );
     expect( fn ).toHaveBeenCalledOnce();
-    expect( validateOutputMock ).toHaveBeenCalledWith( output );
+    expect( parseOutputMock ).toHaveBeenCalledWith( output );
   } );
 } );

package/src/interface/validations/index.js

@@ -1,4 +1,5 @@
 import { ValidationError } from '#errors';
+import { ComponentType } from '#consts';
 import { prettifyError } from 'zod';
 import {
   evaluatorOutputSchema,
@@ -10,84 +11,63 @@ import {
   workflowSchema
 } from './schemas.js';
 
-/**
- * Validates data using a Zod schema
- * @param {unknown} data
- * @param {ZodType} schema
- * @param {string} prefix - Validation error prefix
- * @throws {ValidationError} If validation fails
- * @returns {void}
- */
-const validate = ( data, schema, prefix = '' ) => {
+const capitalize = word => word.at( 0 ).toUpperCase() + word.slice( 1 );
+
+const validate = ( schema, data, prefix ) => {
   if ( !schema ) {
-    return;
+    return data;
   }
-
   const result = schema.safeParse( data );
-  if ( !result.success ) {
+  if ( result.success === false ) {
     throw new ValidationError( `${prefix} validation failed: ${prettifyError( result.error ) }` );
   }
+  return result.data;
 };
 
-export class WorkflowValidator {
+export class Validator {
+  static label;
+  static definitionSchema;
+
   static validateDefinition( definition ) {
-    validate( definition, workflowSchema, 'Workflow' );
+    validate( this.definitionSchema, definition, this.label );
   }
 
   constructor( { name, inputSchema, outputSchema } ) {
     this.name = name;
     this.inputSchema = inputSchema;
     this.outputSchema = outputSchema;
+    this.prefix = `${this.constructor.label} "${this.name}"`;
   }
 
-  validateInput( input ) {
-    validate( input, this.inputSchema, `Workflow "${this.name}" input` );
-  }
-
-  validateOutput( output ) {
-    validate( output, this.outputSchema, `Workflow "${this.name}" output` );
+  parseInput( input ) {
+    return validate( this.inputSchema, input, `${this.prefix} input` );
   }
 
-  validateInvocationOptions( options ) {
-    validate( options, workflowInvocationOptionsSchema, `Workflow "${this.name}" invocation options` );
+  parseOutput( output ) {
+    return validate( this.outputSchema, output, `${this.prefix} output` );
   }
 }
 
-export class StepValidator {
-  static validateDefinition( definition ) {
-    validate( definition, stepSchema, 'Step' );
-  }
-
-  constructor( { name, inputSchema, outputSchema } ) {
-    this.name = name;
-    this.inputSchema = inputSchema;
-    this.outputSchema = outputSchema;
-  }
-
-  validateInput( input ) {
-    validate( input, this.inputSchema, `Step "${this.name}" input` );
-  }
+export class WorkflowValidator extends Validator {
+  static label = capitalize( ComponentType.WORKFLOW );
+  static definitionSchema = workflowSchema;
 
-  validateOutput( output ) {
-    validate( output, this.outputSchema, `Step "${this.name}" output` );
+  parseInvocationOptions( options ) {
+    return validate( workflowInvocationOptionsSchema, options, `${this.prefix} invocation options` );
   }
 }
 
-export class EvaluatorValidator {
-  static validateDefinition( definition ) {
-    validate( definition, evaluatorSchema, 'Evaluator' );
-  }
-  constructor( { name, inputSchema } ) {
-    this.name = name;
-    this.inputSchema = inputSchema;
-  }
+export class StepValidator extends Validator {
+  static label = capitalize( ComponentType.STEP );
+  static definitionSchema = stepSchema;
+}
 
-  validateInput( input ) {
-    validate( input, this.inputSchema, `Evaluator "${this.name}" input` );
-  }
+export class EvaluatorValidator extends Validator {
+  static label = capitalize( ComponentType.EVALUATOR );
+  static definitionSchema = evaluatorSchema;
 
-  validateOutput( output ) {
-    validate( output, evaluatorOutputSchema, `Evaluator "${this.name}" output` );
+  constructor( { name, inputSchema } ) {
+    super( { name, inputSchema, outputSchema: evaluatorOutputSchema } );
   }
 }
 
@@ -96,7 +76,7 @@ export class EvaluatorValidator {
  * @param {object} args - The request arguments
  */
 export function validateRequestPayload( args ) {
-  validate( args, httpRequestSchema, 'Request payload' );
+  validate( httpRequestSchema, args, 'Request payload' );
 };
 
 /**
@@ -104,5 +84,5 @@ export function validateRequestPayload( args ) {
  * @param {object} args - The request arguments
  */
 export function validateExecuteInParallel( args ) {
-  validate( args, executeInParallelSchema, 'ExecuteInParallel' );
+  validate( executeInParallelSchema, args, 'ExecuteInParallel' );
 };