@output.ai/core 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/index.d.ts

@@ -1,49 +1,31 @@
-// Import Zod types for dual schema support
 import type { z } from 'zod';
 import type { ActivityOptions } from '@temporalio/workflow';
 
-// Re-export Zod for consumers to use
+/**
+ * Expose z from Zod as a convenience.
+ */
 export { z } from 'zod';
 
+/*
+╭─────────────────────────╮
+│ C O M M O N  T Y P E S  │╮
+╰─────────────────────────╯│
+ ╰─────────────────────────╯
+*/
+
 /**
  * Type alias for any Zod schema type.
- *
- * Note: The use of `any` here is intentional and necessary. Zod's ZodType has three
- * generic parameters (Output, Def, Input) that vary based on the specific schema type.
- * When we want to accept ANY Zod schema (string, number, object, etc.), we must use
- * `any` for these parameters. Using `unknown` would be too restrictive and would
- * break Zod's type inference system.
- *
- * This is a common pattern in TypeScript when dealing with highly generic types,
- * and Zod itself uses this pattern internally.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyZodSchema = z.ZodType<any, any, any>;
+export type AnyZodSchema = z.ZodType<any, any, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
 
 /**
- * Activity options accepted by step/evaluator/workflow definitions.
- * Exposes supported Temporal ActivityOptions.
+ * Native Temporal configurations for activities.
  *
- * @description Exposes supported Temporal ActivityOptions
- */
-export type Options = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;
-
-/**
- * The last argument when calling workflows is used to configure it
+ * All native options are accepted except 'versioningIntent', 'taskQueue', 'allowEagerDispatch'.
+ *
+ * @see {@link https://typescript.temporal.io/api/interfaces/common.ActivityOptions}
  */
-export type WorkflowCallConfig = {
-
-  /**
-   * Temporal Activity Options
-   */
-  options?: Options,
-
-  /**
-   * Whether this workflow will run detached or not.
-   * Detached workflows called without explicitly awaiting for the result will be "fire-an-forget", outliving the parent.
-   */
-  detached?: boolean
-};
+export type TemporalActivityOptions = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;
 
 /*
 ╭─────────╮
@@ -52,96 +34,127 @@ export type WorkflowCallConfig = {
  ╰─────────╯
 */
 
-/*
- * There are 4 overloads of the "step" function:
- * - with fn receiving input and returning output;
- * - with fn receiving input and returning void;
- * - with fn receiving void and returning output;
- * - with fn receiving void and returning void;
- */
-
-/**
- * Creates logical unit of work defined schema for both input and output.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {z.ZodType} options.outputSchema - Zod schema for the fn output
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- */
-export async function step<
-  InputSchema extends AnyZodSchema,
-  OutputSchema extends AnyZodSchema
->( options: {
-  name: string;
-  description?: string;
-  inputSchema: InputSchema;
-  outputSchema: OutputSchema;
-  fn: ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
-
 /**
- * Creates logical unit of work with defined schema for input only.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<void>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<void>`
+ * The handler function of a step.
+ *
+ * @param input - The step input; it matches the schema defined by `inputSchema`.
+ *
+ * @returns A value matching the schema defined by `outputSchema`.
  */
-export async function step<
-  InputSchema extends AnyZodSchema
->( options: {
-  name: string;
-  description?: string;
-  inputSchema: InputSchema;
-  fn: ( input: z.infer<InputSchema> ) => Promise<void>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<void>;
+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>;
 
 /**
- * Creates logical unit of work with defined schema for output only.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {z.ZodType} options.outputSchema - Zod schema for the fn output
- * @param {function} options.fn - The function logic: `() => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `() => Promise<z.infer<OutputSchema>>`
+ * 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`.
+ *
+ * @param input - The Step input; it matches the schema defined by `inputSchema`.
+ * @returns A value matching the schema defined by `outputSchema`.
  */
-export async function step<
-  OutputSchema extends AnyZodSchema
->( options: {
-  name: string;
-  description?: string;
-  outputSchema: OutputSchema;
-  fn: () => Promise<z.infer<OutputSchema>>;
-  options?: Options;
-} ): () => Promise<z.infer<OutputSchema>>;
+export type StepFunctionWrapper<StepFunction> =
+  Parameters<StepFunction> extends [infer Input] ?
+    ( input: Input ) => ReturnType<StepFunction> :
+    () => ReturnType<StepFunction>;
 
 /**
- * Creates logical unit of work without schemas.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {function} options.fn - The function logic: `() => Promise<void>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `() => Promise<void>`
+ * Creates a step.
+ *
+ * A step is a logical unit of work that can perform I/O. It is translated to a Temporal Activity.
+ *
+ * The step logic is defined in the `fn` handler function.
+ *
+ * The schema of the input that the function receives as the first argument is defined by the `inputSchema` option.
+ *
+ * The output of the `fn` handler must match the schema defined by `outputSchema`; otherwise, a validation error is raised.
+ *
+ * @example
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async input => {
+ *     const result = await ai.call( input.value );
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   fn: async input => {
+ *     await ai.call( input.value );
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   outputSchema: z.string(),
+ *   fn: async () => {
+ *     const result = await ai.call();
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema and outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   fn: async () => {
+ *     await ai.call();
+ *   }
+ * } )
+ * ```
+ *
+ * @remarks
+ * - Never call another step from within a step.
+ * - Never call a workflow from within a step.
+ *
+ * @typeParam InputSchema - Zod schema for the step input
+ * @typeParam OutputSchema - Zod schema for the step output
+ *
+ * @param params - Step parameters
+ * @param params.name - Human-readable step name (must start with a letter or underscore, followed by letters, numbers, or underscores)
+ * @param params.description - Description of the step
+ * @param params.inputSchema - Zod schema for the `fn` input
+ * @param params.outputSchema - Zod schema for the `fn` output
+ * @param params.fn - A handler function containing the step code
+ * @param params.options - Temporal Activity options
+ * @returns The same handler function set at `fn`
  */
-export async function step( options: {
+export declare function step<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+>( params: {
   name: string;
   description?: string;
-  fn: () => Promise<void>;
-  options?: Options;
-} ): () => Promise<void>;
+  inputSchema?: InputSchema;
+  outputSchema?: OutputSchema;
+  fn: StepFunction<InputSchema, OutputSchema>;
+  options?: TemporalActivityOptions;
+} ): StepFunctionWrapper<StepFunction<InputSchema, OutputSchema>>;
 
 /*
 ╭─────────────────╮
@@ -149,96 +162,236 @@ export async function step( options: {
 ╰─────────────────╯│
  ╰─────────────────╯
 */
-/*
- * There are 4 overloads of the "workflow" function:
- * - with fn receiving input and returning output;
- * - with fn receiving input and returning void;
- * - with fn receiving void and returning output;
- * - with fn receiving void and returning void;
+
+/**
+ * Configuration for workflow invocations.
+ *
+ * Allows overriding Temporal Activity options for this workflow.
  */
+export type WorkflowInvocationConfiguration = {
+
+  /**
+   * Native Temporal Activity options
+   */
+  options?: TemporalActivityOptions,
+
+  /**
+   * Configures whether this workflow runs detached.
+   * Detached workflows called without explicitly awaiting the result are "fire-and-forget" and may outlive the parent.
+   */
+  detached?: boolean
+};
 
 /**
- * Creates a workflow orchestrator with defined schema for both input and output.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {z.ZodType} options.inputSchema - Zod schema for workflow input
- * @param {z.ZodType} options.outputSchema - Zod schema for workflow output
- * @param {function} options.fn - Workflow logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ * The second argument passed to the workflow's `fn` function.
  */
-export function workflow<
-  InputSchema extends AnyZodSchema,
-  OutputSchema extends AnyZodSchema
->( options : {
-  name: string,
-  description?: string,
-  inputSchema: InputSchema,
-  outputSchema: OutputSchema,
-  fn: ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>,
-  options?: Options
-} ): ( input: z.infer<InputSchema>, extra?: WorkflowCallConfig ) => Promise<z.infer<OutputSchema>>;
+export type WorkflowContext<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = {
+
+  /**
+   * Functions that allow fine control over the underlying Temporal workflows
+   */
+  control: {
+    /**
+     * Closes the current workflow execution successfully and creates a new workflow execution.
+     *
+     * The new workflow execution is in the same chain as the previous workflow, but it generates another trace file.
+     *
+     * It acts as a checkpoint when the workflow gets too long or approaches certain scaling limits.
+     *
+     * It accepts input with the same schema as the parent workflow function (`inputSchema`).
+     *
+     * Calling this function must be the last statement in the workflow, accompanied by a `return`:
+     *
+     * @example
+     * ```js
+     *   return control.continueAsNew();
+     * ```
+     * Upon returning, the parent workflow execution closes without any output, and the new execution takes its place.
+     *
+     * The function's return type matches `outputSchema`; although no value is returned, the execution is replaced.
+     *
+     * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new}
+     *
+     * @param input - The input for the new run. Omit when the workflow has no input schema.
+     * @returns The workflow output type for type-checking; never returns at runtime.
+     */
+    continueAsNew: InputSchema extends AnyZodSchema ?
+      ( input: z.infer<InputSchema> ) => ( OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void ) :
+      () => ( OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void ),
+
+    /** Indicates whether the Temporal runtime suggests continuing this workflow as new.
+     *
+     * Use this to decide whether to `continueAsNew` before long waits or at loop boundaries.
+     * Prefer returning the `continueAsNew(...)` call immediately when this becomes `true`.
+     *
+     * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new#how-to-test}
+     *
+     * @returns True if a continue-as-new is suggested for the current run; otherwise false.
+     */
+    isContinueAsNewSuggested: () => boolean
+  }
+};
 
 /**
- * Creates a workflow orchestrator with defined schema for input only.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {z.ZodType} options.inputSchema - Zod schema for workflow input
- * @param {function} options.fn - Workflow logic: `(input: z.infer<InputSchema>) => Promise<void>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `(input: z.infer<InputSchema>) => Promise<void>`
+ * The handler function of a workflow.
+ *
+ * @param input - The workflow input; it matches the schema defined by `inputSchema`.
+ * @param context - A context object with tools and information.
+ *
+ * @returns A value matching the schema defined by `outputSchema`.
  */
-export function workflow<
-  InputSchema extends AnyZodSchema
->( options : {
-  name: string,
-  description?: string,
-  inputSchema: InputSchema,
-  fn: ( input: z.infer<InputSchema> ) => Promise<void>,
-  options?: Options
-} ): ( input: z.infer<InputSchema>, extra?: WorkflowCallConfig ) => Promise<void>;
+export type WorkflowFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema>, context: WorkflowContext<InputSchema, OutputSchema> ) =>
+  Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
+  ( input?: undefined | null, context: WorkflowContext<InputSchema, OutputSchema> ) =>
+  Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
 
 /**
- * Creates a workflow orchestrator with defined schema for output only.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {z.ZodType} options.outputSchema - Zod schema for workflow output
- * @param {function} options.fn - Workflow logic: `() => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `() => Promise<z.infer<OutputSchema>>`
+ * A wrapper around the user defined `fn` handler function.
+ *
+ * It accepts the same input and returns the same value, calling the user function inside.
+ *
+ * The second argument is a WorkflowInvocationConfiguration object, allowing workflows configuration overwrite.
+ *
+ * It adds input and output validation based on the `inputSchema`, `outputSchema`.
+ *
+ * @param input - The workflow input; it matches the schema defined by `inputSchema`.
+ * @param config - Additional configuration for the invocation.
+ * @returns A value matching the schema defined by `outputSchema`.
  */
-export function workflow<
-  OutputSchema extends AnyZodSchema
->( options : {
-  name: string,
-  description?: string,
-  outputSchema: OutputSchema,
-  fn: () => Promise<z.infer<OutputSchema>>,
-  options?: Options
-} ): ( input?: undefined | null, extra?: WorkflowCallConfig ) => Promise<z.infer<OutputSchema>>;
+export type WorkflowFunctionWrapper<WorkflowFunction> =
+  [Parameters<WorkflowFunction>[0]] extends [undefined | null] ?
+    ( input?: undefined | null, config?: WorkflowInvocationConfiguration ) => ReturnType<WorkflowFunction> :
+    ( input: Parameters<WorkflowFunction>[0], config?: WorkflowInvocationConfiguration ) => ReturnType<WorkflowFunction>;
 
 /**
- * Creates a workflow orchestrator without defined schemas.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {function} options.fn - Workflow logic: `() => Promise<void>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `() => Promise<void>`
+ * Creates a workflow.
+ *
+ * A workflow is an orchestration of one or more steps. It is translated to a Temporal Workflow.
+ *
+ * The workflow logic is defined in the `fn` handler function.
+ *
+ * The schema of the input that the function receives as the first argument is defined by `inputSchema`.
+ *
+ * The output of the `fn` handler must match `outputSchema`; otherwise, a validation error is raised.
+ *
+ * @remarks
+ * - Workflows should respect the same limitations as Temporal workflows.
+ * - Workflows can invoke steps or evaluators and cannot perform I/O directly.
+ * - The workflow `name` needs to be unique across all workflows in the project.
+ *
+ * @example
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async input => {
+ *     const result = await step( input.value );
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without outputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   fn: async input => {
+ *     await step( input.value );
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without inputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   outputSchema: z.string(),
+ *   fn: async () => {
+ *     const result = await step();
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without inputSchema and outputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   fn: async () => {
+ *     await step();
+ *   }
+ * } )
+ * ```
+ *
+ * @example Using continueAsNew
+ * The function `continueAsNew` (same as Temporal) can be used to create a new workflow with the same ID and pass different input.
+ *
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async ( input, context ) => {
+ *     const result = await step( input.value );
+ *     if ( context.control.isContinueAsNewSuggested() ) {
+ *       return context.control.continueAsNew( input );
+ *     }
+ *
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @param params - Workflow parameters
+ * @param params.name - Human-readable workflow name (must start with a letter or underscore, followed by letters, numbers, or underscores).
+ * @param params.description - Description of the workflow
+ * @param params.inputSchema - Zod schema for workflow input
+ * @param params.outputSchema - Zod schema for workflow output
+ * @param params.fn - A function containing the workflow code
+ * @param params.options - Temporal Activity options
+ * @returns The same handler function set at `fn` with a different signature
  */
-export function workflow( options : {
-  name: string,
-  description?: string,
-  fn: () => Promise<void>,
-  options?: Options
-} ): ( input?: undefined | null, extra?: WorkflowCallConfig ) => Promise<void>;
+export declare function workflow<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+>( params: {
+  name: string;
+  description?: string;
+  inputSchema?: InputSchema;
+  outputSchema?: OutputSchema;
+  fn: WorkflowFunction<InputSchema, OutputSchema>;
+  options?: TemporalActivityOptions;
+} ): WorkflowFunctionWrapper<WorkflowFunction<InputSchema, OutputSchema>>;
 
 /*
 ╭───────────────────╮
@@ -248,31 +401,32 @@ export function workflow( options : {
 */
 
 /**
- * Generic EvaluationResult class, represents the result of an evaluation
+ * Represents the result of an evaluation.
+ *
+ * Generic base class; evaluators must return an instance of an EvaluationResult subclass.
  */
-class EvaluationResult {
+export class EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {any} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence in the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: any; confidence: number; reasoning?: string } ); // eslint-disable-line @typescript-eslint/no-explicit-any
 
   /**
-   * @returns {any} The evaluation result value
+   * @returns The evaluation result value
    */
-
   get value(): any; // eslint-disable-line @typescript-eslint/no-explicit-any
 
   /**
-   * @returns {number} The evaluation result confidence
+   * @returns The evaluation result confidence
    */
   get confidence(): number;
 
   /**
-   * @returns {string} The evaluation result reasoning
+   * @returns The evaluation result reasoning
    */
   get reasoning(): string;
 }
@@ -284,15 +438,15 @@ class EvaluationResult {
 export class EvaluationStringResult extends EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {string} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence on the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: string; confidence: number; reasoning?: string } );
 
   /**
-   * @returns {string} The evaluation result value
+   * @returns The evaluation result value
    */
   get value(): string;
 }
@@ -304,15 +458,15 @@ export class EvaluationStringResult extends EvaluationResult {
 export class EvaluationNumberResult extends EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {number} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence on the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: number; confidence: number; reasoning?: string } );
 
   /**
-   * @returns {number} The evaluation result value
+   * @returns The evaluation result value
    */
   get value(): number;
 }
@@ -324,71 +478,72 @@ export class EvaluationNumberResult extends EvaluationResult {
 export class EvaluationBooleanResult extends EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {boolean} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence on the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: boolean; confidence: number; reasoning?: string } );
 
   /**
-   * @returns {boolean} The evaluation result value
+   * @returns The evaluation result value
    */
   get value(): boolean;
 }
 
-/*
- * There are 2 overloads of the "evaluator" function:
- * - with fn receiving input;
- * - with fn receiving void;
+/**
+ * The handler function of an evaluator.
+ *
+ * @param input - The evaluator input; it matches the schema defined by `inputSchema`.
+ *
+ * @returns The result of the evaluation.
  */
+export type EvaluatorFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  Result extends EvaluationResult
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema> ) => Promise<Result> :
+  () => Promise<Result>;
 
 /**
- * Creates workflow evaluation of work defined schema for input.
- *
- * @param {object} options - Evaluator options
- * @param {string} options.name - Human-readable evaluator name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the evaluator
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ * 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`.
  */
-export async function evaluator<
-  InputSchema extends AnyZodSchema,
-  Result extends EvaluationResult
->( options: {
-  name: string;
-  description?: string;
-  inputSchema: InputSchema;
-  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+export type EvaluatorFunctionWrapper<EvaluatorFunction> =
+  Parameters<EvaluatorFunction> extends [infer Input] ?
+    ( input: Input ) => ReturnType<EvaluatorFunction> :
+    () => ReturnType<EvaluatorFunction>;
 
 /**
- * Creates workflow evaluation without a defined input schema.
- *
- * @param {object} options - Evaluator options
- * @param {string} options.name - Human-readable evaluator name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the evaluator
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ * Creates an evaluation function. It is similar to a step, but must return an EvaluationResult.
+ *
+ * It is translated to a Temporal Activity.
+ *
+ * @param params - Evaluator parameters
+ * @param params.name - Human-readable evaluator name (must start with a letter or underscore, followed by letters, numbers, or underscores)
+ * @param params.description - Description of the evaluator
+ * @param params.inputSchema - Zod schema for the `fn` input
+ * @param params.fn - A function containing the evaluator code
+ * @param params.options - Temporal Activity options
+ * @returns A wrapper function around the `fn` function
  */
-export async function evaluator<
+export declare function evaluator<
   InputSchema extends AnyZodSchema,
   Result extends EvaluationResult
->( options: {
+>( params: {
   name: string;
   description?: string;
-  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+  inputSchema: InputSchema;
+  fn: EvaluatorFunction<InputSchema, Result>;
+  options?: TemporalActivityOptions;
+} ): EvaluatorFunctionWrapper<EvaluatorFunction<InputSchema, Result>>;
 
 /*
 ╭───────────╮
-│ O T H E R │╮
+│ T O O L S │╮
 ╰───────────╯│
  ╰───────────╯
 */
@@ -399,23 +554,32 @@ export async function evaluator<
  * Sends a request via an activity; the workflow will await a corresponding
  * resume signal to continue and return the response payload.
  *
- * @param {object} options - Webhook request options
- * @param {string} options.url - Webhook request url (POST)
- * @param {object} [options.payload] - Webhook request payload
- * @returns {Promise<object>} Resolves with the response payload when resumed
+ * @param params - Webhook request parameters
+ * @param params.url - Webhook request URL (POST)
+ * @param params.payload - Webhook request payload
+ * @returns Resolves with the response payload when resumed
  */
-export function createWebhook( options: { url: string; payload?: object } ): Promise<object>;
+export declare function createWebhook( params: { url: string; payload?: object } ): Promise<object>;
+
+/*
+╭─────────────╮
+│ E R R O R S │╮
+╰─────────────╯│
+ ╰─────────────╯
+*/
 
 /**
  * Error indicating a non-recoverable failure.
  *
- * Use for failures that should not be retried by the workflow runtime.
+ * Throw this error to end the workflow execution altogether without retries.
  */
 export class FatalError extends Error {}
 
 /**
  * Error indicating invalid input or schema validation issues.
  *
- * Use for problems detected during input validation or contract checks.
+ * This error is thrown when there are validation errors, either in the input or output, for steps, evaluators, and workflows.
+ *
+ * It will end the workflow execution without retries.
  */
 export class ValidationError extends Error {}

package/src/index.js

@@ -3,6 +3,7 @@ import { step } from './interface/step.js';
 import { workflow } from './interface/workflow.js';
 import { createWebhook } from './interface/webhook.js';
 import { FatalError, ValidationError } from './errors.js';
+export { continueAsNew } from '@temporalio/workflow';
 import { z } from 'zod';
 
 export {

package/src/interface/workflow.js

@@ -1,5 +1,5 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy } from '@temporalio/workflow';
+import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy, continueAsNew } from '@temporalio/workflow';
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
 import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS } from '#consts';
@@ -35,12 +35,22 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
 
     const { workflowId, memo, startTime } = workflowInfo();
 
+    /* Context Object definition
+       - Control namespace: This object adds functions to interact with Temporal flow mechanisms
+    */
+    const context = {
+      control: {
+        isContinueAsNewSuggested: () => workflowInfo().continueAsNewSuggested,
+        continueAsNew
+      }
+    };
+
     // Root workflows will not have the execution context yet, since it is set here.
     const isRoot = !memo.executionContext;
 
-    // Create the execution context object or preserve if it already exists:
-    // It will always contains the information about the root workflow
-    // It will be used to as context for tracing (connecting events)
+    /* Creates the execution context object or preserve if it already exists:
+       It will always contain the information about the root workflow
+       It will be used to as context for tracing (connecting events) */
     const executionContext = memo.executionContext ?? {
       workflowId,
       workflowName: name,
@@ -83,7 +93,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
             ...( extra?.options && { activityOptions: mergeActivityOptions( activityOptions, extra.options ) } )
           }
         } )
-    }, input );
+    }, input, context );
 
     validateWithSchema( outputSchema, output, `Workflow ${name} output` );
 

package/src/tracing/trace_engine.js

@@ -4,6 +4,7 @@ import { serializeError } from './tools/utils.js';
 import { isStringboolTrue } from '#utils';
 import * as localProcessor from './processors/local/index.js';
 import * as s3Processor from './processors/s3/index.js';
+import { ComponentType } from '#consts';
 
 const traceBus = new EventEmitter();
 const processors = [
@@ -49,11 +50,15 @@ const serializeDetails = details => details instanceof Error ? serializeError( d
  * @param {object} fields - All the trace fields
  * @returns {void}
  */
-export const addEventPhase = ( phase, { kind, name, id, parentId, details, executionContext } ) =>
-  traceBus.emit( 'entry', {
-    executionContext,
-    entry: { kind, phase, name, id, parentId, phase, timestamp: Date.now(), details: serializeDetails( details ) }
-  } );
+export const addEventPhase = ( phase, { kind, name, id, parentId, details, executionContext } ) => {
+  // Ignores internal steps in the actual trace files
+  if ( kind !== ComponentType.INTERNAL_STEP ) {
+    traceBus.emit( 'entry', {
+      executionContext,
+      entry: { kind, phase, name, id, parentId, phase, timestamp: Date.now(), details: serializeDetails( details ) }
+    } );
+  }
+};
 
 /**
  * Adds an Event Phase, complementing the options with parentId and executionContext from the async storage.

package/src/worker/interceptors/workflow.js

@@ -1,5 +1,5 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { workflowInfo, proxySinks, ApplicationFailure } from '@temporalio/workflow';
+import { workflowInfo, proxySinks, ApplicationFailure, ContinueAsNew } from '@temporalio/workflow';
 import { memoToHeaders } from '../sandboxed_utils.js';
 import { mergeActivityOptions } from '#utils';
 // this is a dynamic generated file with activity configs overwrites
@@ -37,6 +37,13 @@ class WorkflowExecutionInterceptor {
       sinks.trace.addWorkflowEventEnd( output );
       return output;
     } catch ( error ) {
+      /* When the error is ContinueAsNew it represents the point where the actual workflow code was
+      delegated to another run. In this case the result in the traces will be the string below and
+      a new trace file will be generated */
+      if ( error instanceof ContinueAsNew ) {
+        sinks.trace.addWorkflowEventEnd( '<continued_as_new>' );
+        throw error;
+      }
       sinks.trace.addWorkflowEventError( error );
       throw new ApplicationFailure( error.message, error.constructor.name );
     }