@output.ai/core 0.0.15 → 0.0.16

package/bin/worker.sh

@@ -18,7 +18,7 @@ fi
 # Get the real script directory (should be node_modules/<pkg>/bin)
 script_dir="$(cd "$(dirname "$real_script")" && pwd)"
 
-# SDK dir is the parent (node_modules/flow-core)
+# SDK dir is the parent (node_modules/output-core)
 sdk_dir="$(dirname "$script_dir")"
 
 cd ${sdk_dir}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "The core module of the output framework",
   "type": "module",
   "main": "src/index.js",
@@ -9,16 +9,12 @@
     "./src",
     "./bin"
   ],
-  "scripts": {
-    "worker": "node ./src/worker/index.js"
-  },
   "bin": {
-    "flow-worker": "./bin/worker.sh",
+    "output-worker": "./bin/worker.sh",
     "outputai": "./bin/worker.sh"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/growthxai/flow-sdk"
+  "scripts": {
+    "worker": "node ./src/worker/index.js"
   },
   "dependencies": {
     "@babel/generator": "7.28.3",
@@ -29,6 +25,7 @@
     "@temporalio/workflow": "1.13.0",
     "zod": "4.1.9"
   },
+  "license": "UNLICENSED",
   "imports": {
     "#consts": "./src/consts.js",
     "#configs": "./src/configs.js",

package/src/consts.js

@@ -7,5 +7,12 @@ export const TraceEvent = {
   WORKFLOW_START: 'workflow_start',
   WORKFLOW_END: 'workflow_end',
   STEP_START: 'step_start',
-  STEP_END: 'step_end'
+  STEP_END: 'step_end',
+  EVALUATOR_START: 'evaluator_start',
+  EVALUATOR_END: 'evaluator_end'
+};
+export const ComponentType = {
+  EVALUATOR: 'evaluator',
+  INTERNAL_STEP: 'internal_step',
+  STEP: 'step'
 };

package/src/index.d.ts

@@ -19,6 +19,13 @@ export { z } from 'zod';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyZodSchema = z.ZodType<any, any, any>;
 
+/*
+╭─────────╮
+│ S T E P │╮
+╰─────────╯│
+ ╰─────────╯
+*/
+
 /*
  * There are 4 overloads of the "step" function:
  * - with fn receiving input and returning output;
@@ -28,7 +35,7 @@ type AnyZodSchema = z.ZodType<any, any, any>;
  */
 
 /**
- * Creates logical unit of work with Zod schemas for both input and output.
+ * 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 "_")
@@ -50,7 +57,7 @@ export async function step<
 } ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
 
 /**
- * Creates logical unit of work with Zod schema for input only.
+ * 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 "_")
@@ -69,7 +76,7 @@ export async function step<
 } ): ( input: z.infer<InputSchema> ) => Promise<void>;
 
 /**
- * Creates logical unit of work with Zod schema for output only.
+ * 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 "_")
@@ -102,6 +109,12 @@ export async function step( options: {
   fn: () => Promise<void>;
 } ): () => Promise<void>;
 
+/*
+╭─────────────────╮
+│ W O R K F L O W │╮
+╰─────────────────╯│
+ ╰─────────────────╯
+*/
 /*
  * There are 4 overloads of the "workflow" function:
  * - with fn receiving input and returning output;
@@ -111,7 +124,7 @@ export async function step( options: {
  */
 
 /**
- * Creates a workflow orchestrator with Zod schemas for both input and output.
+ * Creates a workflow orchestrator defined schema for both input and output.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -133,7 +146,7 @@ export function workflow<
 } ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
 
 /**
- * Creates a workflow orchestrator with Zod schema for input only.
+ * Creates a workflow orchestrator with defined schema for input only.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -152,7 +165,7 @@ export function workflow<
 } ): ( input: z.infer<InputSchema> ) => Promise<void>;
 
 /**
- * Creates a workflow orchestrator with Zod schema for output only.
+ * Creates a workflow orchestrator with defined schema for output only.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -171,7 +184,7 @@ export function workflow<
 } ): () => Promise<z.infer<OutputSchema>>;
 
 /**
- * Creates a workflow orchestrator without schemas.
+ * Creates a workflow orchestrator without defined schemas.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -185,6 +198,155 @@ export function workflow( options : {
   fn: () => Promise<void>
 } ): () => Promise<void>;
 
+/*
+╭───────────────────╮
+│ E V A L U A T O R │╮
+╰───────────────────╯│
+ ╰───────────────────╯
+*/
+
+/**
+ * Generic EvaluationResult class, represents the result of an evaluation
+ */
+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
+   */
+  constructor( args: { value: any; confidence: number; reasoning?: string } ); // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * @returns {any} The evaluation result value
+   */
+
+  get value(): any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * @returns {number} The evaluation result confidence
+   */
+  get confidence(): number;
+
+  /**
+   * @returns {string} The evaluation result reasoning
+   */
+  get reasoning(): string;
+}
+
+/**
+ * An evaluation result where the value is a string
+ * @extends 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
+   */
+  constructor( args: { value: string; confidence: number; reasoning?: string } );
+
+  /**
+   * @returns {string} The evaluation result value
+   */
+  get value(): string;
+}
+
+/**
+ * An evaluation result where the value is a number
+ * @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
+   */
+  constructor( args: { value: number; confidence: number; reasoning?: string } );
+
+  /**
+   * @returns {number} The evaluation result value
+   */
+  get value(): number;
+}
+
+/**
+ * An evaluation result where the value is a boolean
+ * @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
+   */
+  constructor( args: { value: boolean; confidence: number; reasoning?: string } );
+
+  /**
+   * @returns {boolean} The evaluation result value
+   */
+  get value(): boolean;
+}
+
+/*
+ * There are 2 overloads of the "evaluator" function:
+ * - with fn receiving input;
+ * - with fn receiving void;
+ */
+
+/**
+ * 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>>`
+ * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ */
+export async function evaluator<
+  InputSchema extends AnyZodSchema,
+  Result extends EvaluationResult
+>( options: {
+  name: string;
+  description?: string;
+  inputSchema: InputSchema;
+  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
+} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+
+/**
+ * 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>>`
+ * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ */
+export async function evaluator<
+  InputSchema extends AnyZodSchema,
+  Result extends EvaluationResult
+>( options: {
+  name: string;
+  description?: string;
+  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
+} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+
+/*
+╭───────────╮
+│ O T H E R │╮
+╰───────────╯│
+ ╰───────────╯
+*/
+
 /**
  * Create a webhook call that pauses the workflow until resumed via signal.
  *

package/src/index.js

@@ -1,7 +1,24 @@
+import { evaluator, EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult } from './interface/evaluator.js';
 import { step } from './interface/step.js';
 import { workflow } from './interface/workflow.js';
 import { createWebhook } from './interface/webhook.js';
 import { FatalError, ValidationError } from './errors.js';
 import { z } from 'zod';
 
-export { step, workflow, createWebhook, FatalError, ValidationError, z };
+export {
+  // base building blocks
+  evaluator,
+  step,
+  workflow,
+  // Evaluation results
+  EvaluationNumberResult,
+  EvaluationStringResult,
+  EvaluationBooleanResult,
+  // webhook tool
+  createWebhook,
+  // errors
+  FatalError,
+  ValidationError,
+  // zod
+  z
+};

package/src/interface/evaluator.js

@@ -0,0 +1,146 @@
+import { setMetadata } from './metadata.js';
+import { validateEvaluator } from './validations/static.js';
+import { validateWithSchema } from './validations/runtime.js';
+import { ValidationError } from '#errors';
+import { ComponentType } from '#consts';
+import * as z from 'zod';
+
+/**
+ * Error for when EvaluationResult are invalid
+ */
+class EvaluationResultValidationError extends ValidationError {};
+
+/**
+ * Generic EvaluationResult class, represents the result
+ * of an evaluation
+ */
+export class EvaluationResult {
+
+  /**
+   * Returns the evaluation result value
+   * @type {any}
+   */
+  value = null;
+
+  /**
+   * Returns the confidence value, between 0 and 1.
+   * @type {number}
+   */
+  confidence = undefined;
+
+  /**
+   * Returns the reasoning value.
+   * @type {string}
+   */
+  reasoning = undefined;
+
+  static #schema = z.object( {
+    value: z.any(),
+    confidence: z.number(),
+    reasoning: z.string().optional()
+  } );
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationResult.#schema.safeParse( args ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    this.value = args.value;
+    this.confidence = args.confidence;
+    this.reasoning = args.reasoning;
+  }
+};
+
+/**
+ * An evaluation result that uses a string value
+ * @extends EvaluationResult
+ * @property {string} value - The evaluation result value
+ */
+export class EvaluationStringResult extends EvaluationResult {
+  static #valueSchema = z.string();
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationStringResult.#valueSchema.safeParse( args.value ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    super( args );
+  }
+};
+
+/**
+ * An evaluation result that uses a boolean value
+ * @extends EvaluationResult
+ * @property {boolean} value - The evaluation result value
+ */
+export class EvaluationBooleanResult extends EvaluationResult {
+  static #valueSchema = z.boolean();
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationBooleanResult.#valueSchema.safeParse( args.value ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    super( args );
+  }
+};
+
+/**
+ * An evaluation result that uses a number value
+ * @extends EvaluationResult
+ * @property {number} value - The evaluation result value
+ */
+export class EvaluationNumberResult extends EvaluationResult {
+  static #valueSchema = z.number();
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationNumberResult.#valueSchema.safeParse( args.value ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    super( args );
+  }
+};
+
+export function evaluator( { name, description, inputSchema, fn } ) {
+  validateEvaluator( { name, description, inputSchema, fn } );
+
+  const wrapper = async input => {
+    validateWithSchema( inputSchema, input, `Evaluator ${name} input` );
+
+    const output = await fn( input );
+
+    if ( !output instanceof EvaluationResult ) {
+      throw new ValidationError( 'Evaluators must return an EvaluationResult' );
+    }
+
+    return output;
+  };
+
+  setMetadata( wrapper, { name, description, inputSchema, type: ComponentType.EVALUATOR } );
+  return wrapper;
+};

package/src/interface/step.js

@@ -1,15 +1,10 @@
 import { setMetadata } from './metadata.js';
 import { validateStep } from './validations/static.js';
-import { validateWithSchema } from './schema_utils.js';
+import { validateWithSchema } from './validations/runtime.js';
+import { ComponentType } from '#consts';
 
 export function step( { name, description, inputSchema, outputSchema, fn } ) {
-  validateStep( {
-    name,
-    description,
-    inputSchema,
-    outputSchema,
-    fn
-  } );
+  validateStep( { name, description, inputSchema, outputSchema, fn } );
 
   const wrapper = async input => {
     validateWithSchema( inputSchema, input, `Step ${name} input` );
@@ -21,6 +16,6 @@ export function step( { name, description, inputSchema, outputSchema, fn } ) {
     return output;
   };
 
-  setMetadata( wrapper, { name, description, inputSchema, outputSchema } );
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.EVALUATOR } );
   return wrapper;
 };

package/src/interface/{schema_utils.js → validations/runtime.js}

@@ -1,18 +1,5 @@
 import { ValidationError } from '#errors';
 
-/**
- * Detects if a schema is a Zod schema object
- * @param {unknown} schema - The schema to check
- * @returns {boolean} True if the schema is a Zod schema
- */
-export function isZodSchema( schema ) {
-  return schema &&
-         typeof schema === 'object' &&
-         '_def' in schema &&
-         typeof schema.parse === 'function' &&
-         typeof schema.parseAsync === 'function';
-}
-
 /**
  * Validates data against a Zod schema using safeParse
  * @param {unknown} schema - The Zod schema to validate against
@@ -31,4 +18,3 @@ export function validateWithSchema( schema, data, context ) {
     throw new ValidationError( `${context} validation failed: ${result.error.message}` );
   }
 }
-

package/src/interface/validations/runtime.spec.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { validateWithSchema } from './runtime.js';
+import { ValidationError } from '#errors';
+
+describe( 'runtime validations', () => {
+  describe( 'validateWithSchema', () => {
+    it( 'no-ops when schema is falsy', () => {
+      expect( () => validateWithSchema( undefined, { a: 1 }, 'X' ) ).not.toThrow();
+      expect( () => validateWithSchema( null, { a: 1 }, 'X' ) ).not.toThrow();
+    } );
+
+    it( 'passes on valid data', () => {
+      const schema = z.object( { a: z.string(), b: z.number().optional() } );
+      expect( () => validateWithSchema( schema, { a: 'ok' }, 'Test' ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError on invalid data and prefixes context', () => {
+      const schema = z.object( { a: z.string() } );
+      const call = () => validateWithSchema( schema, { a: 1 }, 'MyCtx' );
+      expect( call ).toThrow( ValidationError );
+      try {
+        call();
+      } catch ( e ) {
+        expect( String( e.message ) ).toContain( 'MyCtx validation failed:' );
+      }
+    } );
+  } );
+} );

package/src/interface/validations/schema_utils.js

@@ -0,0 +1,8 @@
+import { ZodType } from 'zod';
+
+/**
+ * Detects if a schema is a ZodType instance
+ * @param {unknown} schema - The schema to check
+ * @returns {boolean} True if the schema is a Zod schema
+ */
+export const isZodSchema = schema => schema instanceof ZodType;

package/src/interface/validations/static.js

@@ -1,5 +1,5 @@
 import * as z from 'zod';
-import { isZodSchema } from '../schema_utils.js';
+import { isZodSchema } from './schema_utils.js';
 
 /**
  * Error is thrown when the definition of a step/workflow has problems
@@ -25,6 +25,8 @@ const stepAndWorkflowSchema = z.object( {
   fn: z.function()
 } );
 
+const evaluatorSchema = stepAndWorkflowSchema.omit( { outputSchema: true } );
+
 const webhookSchema = z.object( {
   url: z.url( { protocol: /^https?$/ } ),
   payload: z.any().optional()
@@ -47,6 +49,16 @@ export function validateStep( args ) {
   validateAgainstSchema( stepAndWorkflowSchema, args );
 };
 
+/**
+ * Validate evaluator payload
+ *
+ * @param {object} args - The evaluator arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateEvaluator( args ) {
+  validateAgainstSchema( evaluatorSchema, args );
+};
+
 /**
  * Validate workflow payload
  *

package/src/interface/validations/static.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { z } from 'zod';
-import { validateStep, validateWorkflow, validateCreateWebhook, StaticValidationError } from './static.js';
+import { validateStep, validateWorkflow, validateCreateWebhook, validateEvaluator, StaticValidationError } from './static.js';
 
 const validArgs = Object.freeze( {
   name: 'valid_name',
@@ -73,6 +73,34 @@ describe( 'interface/validator', () => {
     } );
   } );
 
+  describe( 'validateEvaluator', () => {
+    const base = Object.freeze( {
+      name: 'valid_name',
+      description: 'desc',
+      inputSchema: z.object( {} ),
+      fn: () => {}
+    } );
+
+    it( 'passes for valid args (no outputSchema)', () => {
+      expect( () => validateEvaluator( { ...base } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid name pattern', () => {
+      const error = new StaticValidationError( '✖ Invalid string: must match pattern /^[a-z_][a-z0-9_]*$/i\n  → at name' );
+      expect( () => validateEvaluator( { ...base, name: '-bad' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-Zod inputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at inputSchema' );
+      expect( () => validateEvaluator( { ...base, inputSchema: 'not-a-zod-schema' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received undefined\n  → at fn' );
+      expect( () => validateEvaluator( { ...base, fn: undefined } ) ).toThrow( error );
+    } );
+  } );
+
   describe( 'validate webhook', () => {
     it( 'passes with valid http url', () => {
       expect( () => validateCreateWebhook( { url: 'http://example.com' } ) ).not.toThrow();

package/src/interface/workflow.js

@@ -4,8 +4,8 @@ import { getInvocationDir } from './utils.js';
 import { setMetadata } from './metadata.js';
 import { FatalError, ValidationError } from '#errors';
 import { validateWorkflow } from './validations/static.js';
+import { validateWithSchema } from './validations/runtime.js';
 import { READ_TRACE_FILE, TraceEvent } from '#consts';
-import { validateWithSchema } from './schema_utils.js';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -19,13 +19,7 @@ const temporalActivityConfigs = {
 };
 
 export function workflow( { name, description, inputSchema, outputSchema, fn } ) {
-  validateWorkflow( {
-    name,
-    description,
-    inputSchema,
-    outputSchema,
-    fn
-  } );
+  validateWorkflow( { name, description, inputSchema, outputSchema, fn } );
   const workflowPath = getInvocationDir();
 
   const steps = proxyActivities( temporalActivityConfigs );
@@ -53,6 +47,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn } )
       // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
       const output = await fn.call( {
         invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
+        invokeEvaluator: async ( evaluatorName, input ) => steps[`${workflowPath}#${evaluatorName}`]( input ),
 
         startWorkflow: async ( childName, input ) => {
 

package/src/internal_activities/index.js

@@ -1,6 +1,8 @@
 import { FatalError } from '#errors';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { setMetadata } from '../interface/metadata.js';
+import { ComponentType } from '#consts';
 
 const callerDir = process.argv[2];
 
@@ -38,6 +40,8 @@ export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
   }
 };
 
+setMetadata( sendWebhookPost, { type: ComponentType.INTERNAL_STEP } );
+
 /**
  * Read the trace file of a given execution and returns the content
  *
@@ -65,3 +69,5 @@ export const readTraceFile = async ( { workflowType, workflowId } ) => {
   const file = join( dir, matchingFile );
   return existsSync( file ) ? readFileSync( file, 'utf-8' ).split( '\n' ) : [];
 };
+
+setMetadata( readTraceFile, { type: ComponentType.INTERNAL_STEP, skipTrace: true } );

package/src/worker/catalog_workflow/catalog.js

@@ -73,6 +73,18 @@ class CatalogEntry {
   };
 }
 
+/**
+ * Describes a single activity within a workflow.
+ *
+ * @class
+ * @extends CatalogEntry
+ */
+export class CatalogActivity extends CatalogEntry {}
+
+/**
+ * @param { CatalogWorkflowOptions}
+ */
+
 /**
  * Describes a single workflow within the catalog.
  *
@@ -87,19 +99,16 @@ export class CatalogWorkflow extends CatalogEntry {
   activities;
 
   /**
-   * @inheritdoc
-   * @param {Array<CatalogActivity>} params.activities - Activities referenced by this workflow.
+   * @param {Object} params - Entry parameters.
+   * @param {string} params.name - Name of the entry.
+   * @param {string} [params.description] - Optional description.
+   * @param {object} [params.inputSchema] - JSON schema describing the expected input.
+   * @param {object} [params.outputSchema] - JSON schema describing the produced output.
+   * @param {string} params.path - Absolute path of the entity in the file system.
+   * @param {Array<CatalogActivity>} params.activities - Each activity of this workflow
    */
   constructor( { activities, ...args } ) {
     super( args );
     this.activities = activities;
   };
 };
-
-/**
- * Describes a single activity within a workflow.
- *
- * @class
- * @extends CatalogEntry
- */
-export class CatalogActivity extends CatalogEntry {}

package/src/worker/index.js

@@ -47,7 +47,7 @@ const callerDir = process.argv[2];
     sinks,
     interceptors: {
       workflowModules: [ join( __dirname, './interceptors/workflow.js' ) ],
-      activityInbound: [ () => new ActivityExecutionInterceptor() ]
+      activityInbound: [ () => new ActivityExecutionInterceptor( activities ) ]
     },
     maxConcurrentWorkflowTaskExecutions: maxWorkflows,
     maxConcurrentActivityTaskExecutions: maxActivities,

package/src/worker/interceptors/activity.js

@@ -2,7 +2,8 @@ import { Context } from '@temporalio/activity';
 import { Storage } from '../async_storage.js';
 import { trace } from '../tracer/index.js';
 import { headersToObject } from '../sandboxed_utils.js';
-import { THIS_LIB_NAME, TraceEvent } from '#consts';
+import { THIS_LIB_NAME } from '#consts';
+import { METADATA_ACCESS_SYMBOL } from '#consts';
 
 /*
   This interceptor is called for every activity execution
@@ -14,14 +15,26 @@ import { THIS_LIB_NAME, TraceEvent } from '#consts';
   Some information it needs for its context comes from Temporal's Activity Context others are injected in the headers
 */
 export class ActivityExecutionInterceptor {
+  constructor( activities ) {
+    this.activities = activities;
+  };
+
   async execute( input, next ) {
     const { workflowExecution: { workflowId }, activityId, activityType, workflowType } = Context.current().info;
+
+    const activityFn = this.activities?.[activityType];
+    const { type: componentType, skipTrace } = activityFn?.[METADATA_ACCESS_SYMBOL];
+
     const context = { workflowId, workflowType, activityId, activityType, ...headersToObject( input.headers ) };
 
     return Storage.runWithContext( async _ => {
-      trace( { lib: THIS_LIB_NAME, event: TraceEvent.STEP_START, input: input.args } );
+      if ( !skipTrace ) {
+        trace( { lib: THIS_LIB_NAME, event: `${componentType}_start`, input: input.args } );
+      }
       const output = await next( input );
-      trace( { lib: THIS_LIB_NAME, event: TraceEvent.STEP_END, output } );
+      if ( !skipTrace ) {
+        trace( { lib: THIS_LIB_NAME, event: `${componentType}_end`, output } );
+      }
       return output;
     }, context );
   }

package/src/worker/loader.js

@@ -12,10 +12,10 @@ const __dirname = dirname( fileURLToPath( import.meta.url ) );
 
 // returns a map of activities, where the key is they path + name and the value is the function with metadata
 export async function loadActivities( path ) {
-  const activityPaths = recursiveNavigateWhileCollecting( path, [ 'steps.js' ] );
+  const activityPaths = recursiveNavigateWhileCollecting( path, [ 'steps.js', 'evaluators.js' ] );
   const activities = [];
   for await ( const { component, metadata, pathname, path } of iteratorOverImportedComponents( activityPaths ) ) {
-    console.log( '[Core.Scanner]', 'Activity loaded:', metadata.name, 'at', pathname );
+    console.log( '[Core.Scanner]', 'Component loaded:', metadata.type, metadata.name, 'at', pathname );
     activities[`${path}#${metadata.name}`] = component;
   }
 

package/src/worker/tracer/index.js

@@ -48,7 +48,7 @@ export function trace( { lib, event, input = undefined, output = undefined } ) {
     rootWorkflowType
   } = Storage.load();
 
-  const entry = { lib, event, input, output, timestamp: now, stepId, stepName, workflowId, workflowType, workflowPath, parentWorkflowId };
+  const entry = { event, input, lib, output, parentWorkflowId, stepId, stepName, timestamp: now, workflowId, workflowPath, workflowType };
 
   // test for rootWorkflow to append to the same file as the parent/grandparent
   const outputDir = join( callerDir, 'logs', 'runs', rootWorkflowType ?? workflowType );

package/src/worker/tracer/index.test.js

@@ -4,7 +4,7 @@ import { tmpdir, EOL } from 'node:os';
 import { join } from 'path';
 import { THIS_LIB_NAME } from '#consts';
 
-const createTempDir = () => mkdtempSync( join( tmpdir(), 'flow-sdk-trace-' ) );
+const createTempDir = () => mkdtempSync( join( tmpdir(), 'output-sdk-trace-' ) );
 
 // Single mocks (configured per-test by mutating the backing objects)
 const mockConfig = { tracing: { enabled: false } };
@@ -32,7 +32,6 @@ describe( 'tracer/index', () => {
     vi.clearAllMocks();
     vi.useFakeTimers();
     vi.setSystemTime( new Date( '2020-01-01T00:00:00.000Z' ) );
-
   } );
 
   afterEach( () => {

package/src/worker/tracer/tracer_tree.js

@@ -46,11 +46,12 @@ export const buildLogTree = src => {
     const { event, workflowId, workflowType, workflowPath, parentWorkflowId, stepId, stepName, input, output, timestamp } = entry;
 
     const baseEntry = { children: [], startedAt: timestamp, workflowId };
-    if ( event === TraceEvent.STEP_START ) {
-      stepsMap.set( `${workflowId}:${stepId}`, { event: 'step', input, stepId, stepName, ...baseEntry } );
+    if ( [ TraceEvent.EVALUATOR_START, TraceEvent.STEP_START ].includes( event ) ) {
+      const eventName = event === TraceEvent.EVALUATOR_START ? 'evaluator' : 'step';
+      stepsMap.set( `${workflowId}:${stepId}`, { event: eventName, input, stepId, stepName, ...baseEntry } );
     }
 
-    if ( event === TraceEvent.STEP_END ) {
+    if ( [ TraceEvent.EVALUATOR_END, TraceEvent.STEP_END ].includes( event ) ) {
       Object.assign( stepsMap.get( `${workflowId}:${stepId}` ) ?? {}, { output, endedAt: timestamp } );
     }
 

package/src/worker/tracer/tracer_tree.test.js

@@ -7,7 +7,7 @@ import { EOL } from 'os';
 import { buildLogTree } from './tracer_tree.js';
 import { THIS_LIB_NAME, TraceEvent } from '#consts';
 
-const createTempDir = () => mkdtempSync( join( tmpdir(), 'flow-sdk-trace-tree-' ) );
+const createTempDir = () => mkdtempSync( join( tmpdir(), 'output-sdk-trace-tree-' ) );
 
 describe( 'tracer/tracer_tree', () => {
   it( 'builds a tree JSON from a raw log file', () => {

package/src/worker/webpack_loaders/workflow_rewriter/collect_target_imports.js

@@ -2,9 +2,11 @@ import traverseModule from '@babel/traverse';
 import {
   buildWorkflowNameMap,
   getLocalNameFromDestructuredProperty,
+  isEvaluatorsPath,
   isStepsPath,
   isWorkflowPath,
   buildStepsNameMap,
+  buildEvaluatorsNameMap,
   toAbsolutePath
 } from './tools.js';
 import {
@@ -34,15 +36,16 @@ const traverse = traverseModule.default ?? traverseModule;
  * @returns {{ stepImports: Array<{localName:string,stepName:string}>,
  *  flowImports: Array<{localName:string,workflowName:string}> }} Collected info mappings.
  */
-export default function collectTargetImports( ast, fileDir, { stepsNameCache, workflowNameCache } ) {
+export default function collectTargetImports( ast, fileDir, { stepsNameCache, workflowNameCache, evaluatorsNameCache } ) {
   const stepImports = [];
   const flowImports = [];
+  const evaluatorImports = [];
 
   traverse( ast, {
     ImportDeclaration: path => {
       const src = path.node.source.value;
       // Ignore other imports
-      if ( !isStepsPath( src ) && !isWorkflowPath( src ) ) {
+      if ( !isStepsPath( src ) && !isWorkflowPath( src ) && !isEvaluatorsPath( src ) ) {
         return;
       }
 
@@ -58,6 +61,17 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
           }
         }
       }
+      if ( isEvaluatorsPath( src ) ) {
+        const nameMap = buildEvaluatorsNameMap( absolutePath, evaluatorsNameCache );
+        for ( const s of path.node.specifiers.filter( s => isImportSpecifier( s ) ) ) {
+          const importedName = s.imported.name;
+          const localName = s.local.name;
+          const evaluatorName = nameMap.get( importedName );
+          if ( evaluatorName ) {
+            evaluatorImports.push( { localName, evaluatorName } );
+          }
+        }
+      }
       if ( isWorkflowPath( src ) ) {
         const { named, default: defName } = buildWorkflowNameMap( absolutePath, workflowNameCache );
         for ( const s of path.node.specifiers ) {
@@ -94,7 +108,7 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
 
       const req = firstArgument.value;
       // Must be steps/workflows module
-      if ( !isStepsPath( req ) && !isWorkflowPath( req ) ) {
+      if ( !isStepsPath( req ) && !isWorkflowPath( req ) && !isEvaluatorsPath( req ) ) {
         return;
       }
 
@@ -116,6 +130,23 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
         } else {
           path.remove();
         }
+      } else if ( isEvaluatorsPath( req ) && isObjectPattern( path.node.id ) ) {
+        const nameMap = buildEvaluatorsNameMap( absolutePath, evaluatorsNameCache );
+        for ( const prop of path.node.id.properties.filter( prop => isObjectProperty( prop ) && isIdentifier( prop.key ) ) ) {
+          const importedName = prop.key.name;
+          const localName = getLocalNameFromDestructuredProperty( prop );
+          if ( localName ) {
+            const evaluatorName = nameMap.get( importedName );
+            if ( evaluatorName ) {
+              evaluatorImports.push( { localName, evaluatorName } );
+            }
+          }
+        }
+        if ( isVariableDeclaration( path.parent ) && path.parent.declarations.length === 1 ) {
+          path.parentPath.remove();
+        } else {
+          path.remove();
+        }
       } else if ( isWorkflowPath( req ) && isIdentifier( path.node.id ) ) {
         const { default: defName } = buildWorkflowNameMap( absolutePath, workflowNameCache );
         const localName = path.node.id.name;
@@ -129,5 +160,5 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
     }
   } );
 
-  return { stepImports, flowImports };
+  return { stepImports, evaluatorImports, flowImports };
 };

package/src/worker/webpack_loaders/workflow_rewriter/collect_target_imports.spec.js

@@ -16,6 +16,9 @@ describe( 'collect_target_imports', () => {
       'export const StepA = step({ name: "step.a" })',
       'export const StepB = step({ name: "step.b" })'
     ].join( '\n' ) );
+    writeFileSync( join( dir, 'evaluators.js' ), [
+      'export const EvalA = evaluator({ name: "eval.a" })'
+    ].join( '\n' ) );
     writeFileSync( join( dir, 'workflow.js' ), [
       'export const FlowA = workflow({ name: "flow.a" })',
       'export default workflow({ name: "flow.def" })'
@@ -23,16 +26,18 @@ describe( 'collect_target_imports', () => {
 
     const source = [
       'import { StepA } from "./steps.js";',
+      'import { EvalA } from "./evaluators.js";',
       'import WF, { FlowA } from "./workflow.js";',
       'const x = 1;'
     ].join( '\n' );
 
     const ast = makeAst( source, join( dir, 'file.js' ) );
-    const { stepImports, flowImports } = collectTargetImports(
+    const { stepImports, evaluatorImports, flowImports } = collectTargetImports(
       ast,
       dir,
-      { stepsNameCache: new Map(), workflowNameCache: new Map() }
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
     );
+    expect( evaluatorImports ).toEqual( [ { localName: 'EvalA', evaluatorName: 'eval.a' } ] );
 
     expect( stepImports ).toEqual( [ { localName: 'StepA', stepName: 'step.a' } ] );
     expect( flowImports ).toEqual( [
@@ -48,20 +53,23 @@ describe( 'collect_target_imports', () => {
   it( 'collects CJS requires and removes declarators (steps + default workflow)', () => {
     const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-' ) );
     writeFileSync( join( dir, 'steps.js' ), 'export const StepB = step({ name: "step.b" })\n' );
+    writeFileSync( join( dir, 'evaluators.js' ), 'export const EvalB = evaluator({ name: "eval.b" })\n' );
     writeFileSync( join( dir, 'workflow.js' ), 'export default workflow({ name: "flow.c" })\n' );
 
     const source = [
       'const { StepB } = require("./steps.js");',
+      'const { EvalB } = require("./evaluators.js");',
       'const WF = require("./workflow.js");',
       'const obj = {};'
     ].join( '\n' );
 
     const ast = makeAst( source, join( dir, 'file.js' ) );
-    const { stepImports, flowImports } = collectTargetImports(
+    const { stepImports, evaluatorImports, flowImports } = collectTargetImports(
       ast,
       dir,
-      { stepsNameCache: new Map(), workflowNameCache: new Map() }
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
     );
+    expect( evaluatorImports ).toEqual( [ { localName: 'EvalB', evaluatorName: 'eval.b' } ] );
 
     expect( stepImports ).toEqual( [ { localName: 'StepB', stepName: 'step.b' } ] );
     expect( flowImports ).toEqual( [ { localName: 'WF', workflowName: 'flow.c' } ] );

package/src/worker/webpack_loaders/workflow_rewriter/index.mjs

@@ -10,6 +10,7 @@ const generate = generatorModule.default ?? generatorModule;
 
 // Caches to avoid re-reading files during a build
 const stepsNameCache = new Map(); // path -> Map<exported, stepName>
+const evaluatorsNameCache = new Map(); // path -> Map<exported, evaluatorName>
 const workflowNameCache = new Map(); // path -> { default?: name, named: Map<exported, flowName> }
 
 /**
@@ -25,20 +26,20 @@ const workflowNameCache = new Map(); // path -> { default?: name, named: Map<exp
 export default function stepImportRewriterAstLoader( source, inputMap ) {
   this.cacheable?.( true );
   const callback = this.async?.() ?? this.callback;
-  const cache = { stepsNameCache, workflowNameCache };
+  const cache = { stepsNameCache, evaluatorsNameCache, workflowNameCache };
 
   try {
     const filename = this.resourcePath;
     const ast = parse( String( source ), filename );
     const fileDir = dirname( filename );
-    const { stepImports, flowImports } = collectTargetImports( ast, fileDir, cache );
+    const { stepImports, evaluatorImports, flowImports } = collectTargetImports( ast, fileDir, cache );
 
     // No imports
-    if ( stepImports.length + flowImports.length === 0 ) {
+    if ( [].concat( stepImports, evaluatorImports, flowImports ).length === 0 ) {
       return callback( null, source, inputMap );
     }
 
-    const rewrote = rewriteFnBodies( ast, stepImports, flowImports );
+    const rewrote = rewriteFnBodies( { ast, stepImports, evaluatorImports, flowImports } );
     // No edits performed
     if ( !rewrote ) {
       return callback( null, source, inputMap );

package/src/worker/webpack_loaders/workflow_rewriter/rewrite_fn_bodies.js

@@ -15,12 +15,14 @@ const traverse = traverseModule.default ?? traverseModule;
  * `this.invokeStep('name', ...)` and `FlowY(...)` with
  * `this.startWorkflow('name', ...)`.
  *
- * @param {import('@babel/types').File} ast - Parsed file AST.
- * @param {Array<{localName:string,stepName:string}>} stepImports - Step imports.
- * @param {Array<{localName:string,workflowName:string}>} flowImports - Workflow imports.
+ * @param {object} params
+ * @param {import('@babel/types').File} params.ast - Parsed file AST.
+ * @param {Array<{localName:string,stepName:string}>} params.stepImports - Step imports.
+ * @param {Array<{localName:string,evaluatorName:string}>} params.evaluatorImports - Evaluator imports.
+ * @param {Array<{localName:string,workflowName:string}>} params.flowImports - Workflow imports.
  * @returns {boolean} True if the AST was modified; false otherwise.
  */
-export default function rewriteFnBodies( ast, stepImports, flowImports ) {
+export default function rewriteFnBodies( { ast, stepImports, evaluatorImports, flowImports } ) {
   const state = { rewrote: false };
   traverse( ast, {
     ObjectProperty: path => {
@@ -56,6 +58,13 @@ export default function rewriteFnBodies( ast, stepImports, flowImports ) {
             state.rewrote = true;
             return; // Stop after rewriting as step call
           }
+          const evaluator = evaluatorImports.find( x => x.localName === callee.name );
+          if ( evaluator ) {
+            const args = cPath.node.arguments;
+            cPath.replaceWith( createThisMethodCall( 'invokeEvaluator', evaluator.evaluatorName, args ) );
+            state.rewrote = true;
+            return; // Stop after rewriting as evaluator call
+          }
           const flow = flowImports.find( x => x.localName === callee.name );
           if ( flow ) {
             const args = cPath.node.arguments;

package/src/worker/webpack_loaders/workflow_rewriter/rewrite_fn_bodies.spec.js

@@ -16,17 +16,31 @@ describe( 'rewrite_fn_bodies', () => {
     const stepImports = [ { localName: 'StepA', stepName: 'step.a' } ];
     const flowImports = [ { localName: 'FlowB', workflowName: 'flow.b' } ];
 
-    const rewrote = rewriteFnBodies( ast, stepImports, flowImports );
+    const rewrote = rewriteFnBodies( { ast, stepImports, evaluatorImports: [], flowImports } );
     expect( rewrote ).toBe( true );
 
     const code = ast.program.body.map( n => n.type ).length; // smoke: ast mutated
     expect( code ).toBeGreaterThan( 0 );
   } );
 
+  it( 'rewrites evaluator calls to this.invokeEvaluator', () => {
+    const src = [
+      'const obj = {',
+      '  fn: async (x) => {',
+      '    EvalA(3);',
+      '  }',
+      '}'
+    ].join( '\n' );
+    const ast = parse( src, 'file.js' );
+    const evaluatorImports = [ { localName: 'EvalA', evaluatorName: 'eval.a' } ];
+    const rewrote = rewriteFnBodies( { ast, stepImports: [], evaluatorImports, flowImports: [] } );
+    expect( rewrote ).toBe( true );
+  } );
+
   it( 'does nothing when no matching calls are present', () => {
     const src = [ 'const obj = { fn: function() { other(); } }' ].join( '\n' );
     const ast = parse( src, 'file.js' );
-    const rewrote = rewriteFnBodies( ast, [], [] );
+    const rewrote = rewriteFnBodies( { ast, stepImports: [], evaluatorImports: [], flowImports: [] } );
     expect( rewrote ).toBe( false );
   } );
 } );

package/src/worker/webpack_loaders/workflow_rewriter/tools.js

@@ -106,6 +106,13 @@ export const toFunctionExpression = arrow => {
  */
 export const isStepsPath = value => /(^|\/)steps\.js$/.test( value );
 
+/**
+ * Check if a module specifier or request string points to evaluators.js.
+ * @param {string} value - Module path or request string.
+ * @returns {boolean} True if it matches evaluators.js.
+ */
+export const isEvaluatorsPath = value => /(^|\/)evaluators\.js$/.test( value );
+
 /**
  * Check if a module specifier or request string points to workflow.js.
  * @param {string} value - Module path or request string.
@@ -165,14 +172,18 @@ export const resolveNameFromOptions = ( optionsNode, consts, errorMessagePrefix
 };
 
 /**
- * Build a map from exported step variable name to declared step name.
- * Parses the steps module and extracts `step({ name: '...' })` names.
- * @param {string} path - Absolute path to the steps module file.
- * @param {Map<string, Map<string,string>>} cache - Cache of computed step name maps.
- * @returns {Map<string,string>} Exported identifier -> step name.
- * @throws {Error} When a step name is invalid (non-static or missing).
+ * Build a map of exported component identifiers to declared names by scanning a module.
+ * Coerces only static, analyzable forms: `export const X = callee({ name: '...' })`.
+ *
+ * @param {object} params
+ * @param {string} params.path - Absolute path to the module file.
+ * @param {Map<string, Map<string,string>>} params.cache - Cache for memoizing results by file path.
+ * @param {('step'|'evaluator')} params.calleeName - Factory function identifier to match.
+ * @param {string} params.invalidMessagePrefix - Prefix used in thrown errors when name is invalid.
+ * @returns {Map<string,string>} Map of `exportedIdentifier` -> `declaredName`.
+ * @throws {Error} When names are missing, dynamic, or otherwise non-static.
  */
-export const buildStepsNameMap = ( path, cache ) => {
+const buildComponentNameMap = ( { path, cache, calleeName, invalidMessagePrefix } ) => {
   if ( cache.has( path ) ) {
     return cache.get( path );
   }
@@ -180,24 +191,46 @@ export const buildStepsNameMap = ( path, cache ) => {
   const ast = parse( text, path );
   const consts = extractTopLevelStringConsts( ast );
 
-  const stepMap = ast.program.body
+  const result = ast.program.body
     .filter( node => isExportNamedDeclaration( node ) && isVariableDeclaration( node.declaration ) )
     .reduce( ( map, node ) => {
-
       node.declaration.declarations
-        .filter( dec => isIdentifier( dec.id ) && isCallExpression( dec.init ) && isIdentifier( dec.init.callee, { name: 'step' } ) )
+        .filter( dec => isIdentifier( dec.id ) && isCallExpression( dec.init ) && isIdentifier( dec.init.callee, { name: calleeName } ) )
         .map( dec => [
           dec,
-          resolveNameFromOptions( dec.init.arguments[0], consts, `Invalid step name in ${path} for "${dec.id.name}"` )
+          resolveNameFromOptions( dec.init.arguments[0], consts, `${invalidMessagePrefix} ${path} for "${dec.id.name}"` )
         ] )
         .forEach( ( [ dec, name ] ) => map.set( dec.id.name, name ) );
       return map;
     }, new Map() );
 
-  cache.set( path, stepMap );
-  return stepMap;
+  cache.set( path, result );
+  return result;
 };
 
+export const buildStepsNameMap = ( path, cache ) => buildComponentNameMap( {
+  path,
+  cache,
+  calleeName: 'step',
+  invalidMessagePrefix: 'Invalid step name in'
+} );
+
+/**
+ * Build a map from exported evaluator identifier to declared evaluator name.
+ * Parses `evaluators.js` for `export const X = evaluator({ name: '...' })`.
+ *
+ * @param {string} path - Absolute path to the evaluators module file.
+ * @param {Map<string, Map<string,string>>} cache - Cache of computed evaluator name maps.
+ * @returns {Map<string,string>} Exported identifier -> evaluator name.
+ * @throws {Error} When a evaluator name is invalid (non-static or missing).
+ */
+export const buildEvaluatorsNameMap = ( path, cache ) => buildComponentNameMap( {
+  path,
+  cache,
+  calleeName: 'evaluator',
+  invalidMessagePrefix: 'Invalid evaluator name in'
+} );
+
 /**
  * Build a structure with default and named workflow names from a workflow module.
  * Extracts names from `workflow({ name: '...' })` calls.

package/src/worker/webpack_loaders/workflow_rewriter/tools.spec.js

@@ -15,7 +15,8 @@ import {
   createThisMethodCall,
   resolveNameFromOptions,
   buildStepsNameMap,
-  buildWorkflowNameMap
+  buildWorkflowNameMap,
+  buildEvaluatorsNameMap
 } from './tools.js';
 
 describe( 'workflow_rewriter tools', () => {
@@ -72,6 +73,23 @@ describe( 'workflow_rewriter tools', () => {
     rmSync( dir, { recursive: true, force: true } );
   } );
 
+  it( 'buildEvaluatorsNameMap: reads names from evaluators module and caches result', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'tools-evals-' ) );
+    const evalsPath = join( dir, 'evaluators.js' );
+    writeFileSync( evalsPath, [
+      'export const EvalA = evaluator({ name: "eval.a" })',
+      'export const EvalB = evaluator({ name: "eval.b" })'
+    ].join( '\n' ) );
+    const cache = new Map();
+    const map1 = buildEvaluatorsNameMap( evalsPath, cache );
+    expect( map1.get( 'EvalA' ) ).toBe( 'eval.a' );
+    expect( map1.get( 'EvalB' ) ).toBe( 'eval.b' );
+    expect( cache.get( evalsPath ) ).toBe( map1 );
+    const map2 = buildEvaluatorsNameMap( evalsPath, cache );
+    expect( map2 ).toBe( map1 );
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
   it( 'getLocalNameFromDestructuredProperty: handles { a }, { a: b }, { a: b = 1 }', () => {
     // { a }
     const p1 = t.objectProperty( t.identifier( 'a' ), t.identifier( 'a' ), false, true );
@@ -88,7 +106,7 @@ describe( 'workflow_rewriter tools', () => {
   } );
 
   it( 'buildWorkflowNameMap: reads named and default workflow names and caches', () => {
-    const dir = mkdtempSync( join( tmpdir(), 'tools-flow-' ) );
+    const dir = mkdtempSync( join( tmpdir(), 'tools-output-' ) );
     const wfPath = join( dir, 'workflow.js' );
     writeFileSync( wfPath, [
       'export const FlowA = workflow({ name: "flow.a" })',