@output.ai/core 0.1.1 → 0.1.2

package/README.md

@@ -4,24 +4,30 @@ Provides tools to develop and run a workflow, which is a well defined logical un
 
 ## Structure
 
-Workflows are defined using core functions "workflow" and "step", separate files:
+Workflows are defined using core functions ("workflow", "step", "evaluator"), these are defined in separate files, and must be placed within the same folder:
 
 ```
 └ workflows
   └ example
     ├ workflow.ts|js <- workflow entry point
-    ├ steps.ts|js <- file with each step of this workflow
+    ├ steps.ts|js <- file containing steps used by the workflow
+    ├ evaluators.ts|js <- file containing evaluating functions
     └ prompt.prompt <- a prompt file
   └ other-example
 
 ```
 
-Think that workflows is the orchestrator and steps are executors. So the workflow only call the steps and the steps call the IO operations, like APIs, DBs, LLMs, etc.
+Workflows are the orchestrator and steps are executors. So the workflow only call the steps and the steps call the IO operations, like APIs, DBs, LLMs, etc. Evaluators are just another different flavor for steps, they work the same, but must return an `EvaluationResult` object.
 
-## Workflow code
+## Components
 
-### workflow.js
+### Workflow
 
+The main code, must contain only deterministic orchestration code.
+
+File: `workflow.js`
+
+Example:
 ```js
 import { workflow, z } from '@output.ai/workflow';
 import { guessByName } from './steps.js';
@@ -42,8 +48,13 @@ export default workflow( {
 })
 ```
 
-### steps.js
+### Step
+
+Re-usable units of work that can contain IO, used by the workflow.
 
+File: `steps.js`
+
+Example:
 ```js
 import { api } from './api.js'
 
@@ -58,9 +69,73 @@ export const guessByName = step( {
 } )
 ```
 
-## webhooks
+### Shared Steps
+
+By default, steps are exclusive to the workflow, so it is not passible to use these steps from elsewhere. In order to have shared steps and make them accessible in different workflows, create a shared steps file. This file can be relatively imported anywhere.
+
+File: `shared_steps.js`
+
+Example:
+```js
+export const mySharedStep = step( {
+  name: 'mySharedStep',
+  ...
+} )
+```
+
+And the usage is the same as any step:
+`workflow.js`
+```js
+import { mySharedStep } from '../../tools/shared_steps.js'
+```
+
+### Evaluators
+
+Steps that analyze LLM response, or take other measurements are contained in evaluators.
+
+File: `evaluators.js`
+
+Example:
+```js
+import { evaluator, EvaluationStringResult } from './api.js'
+
+export const judgeResult = evaluator( {
+  name: 'judgeResult',
+  inputSchema: z.string(),
+  fn: async name => {
+    ...
+    return new EvaluationStringResult({
+      value: 'good',
+      confidence: .95
+    });
+  }
+} )
+```
+
+Its usage is the same as steps:
+`workflow.js`
+```js
+import { workflow, z } from '@output.ai/workflow';
+import { judgeResult } from './evaluators.js';
 
-workflows can call webhooks that will stop their execution until an answer is given back.
+export default workflow( {
+  name: 'guessMyProfession',
+  inputSchema: z.object( {
+    name: z.string()
+  } ),
+  outputSchema: z.object( {
+    result: z.string()
+  } ),
+  fn: async input => {
+    const judgment = await judgeResult( input.name );
+    return { result: judgement.value };
+  }
+})
+```
+
+## Webhooks
+
+Workflows can call webhooks that will stop their execution until an answer is given back.
 
 ```js
 import { workflow, createWebhook } from '@output.ai/workflow';
@@ -107,6 +182,21 @@ POST http://locahost:3001/workflow/feedback
   }
 ```
 
+## Options
+
+All core interface functions: workflow, step, evaluator have similar signature, with the following options:
+- name: The function name, used to call it internally and identify it in the trace files, must be a code friendly string;
+- description: Human description of the workflow/step, used for the catalog;
+- inputSchema: a zod object indicating the type of the argument received by the `fn` function. It is validated. Omit if it doesn't have input arguments;
+- outputSchema: a zod object indicating the type of that the `fn` function returns. It is validated. Omit if it is void. Evaluators do not have this option, since they must always return an EvaluationResult object;
+- fn: The actual implementation of the workflow/step, including all its logic.
+- options: Advanced options that will overwrite Temporal's ActivityOptions when calling activities.
+
+  If used on `workflow()` it will apply for all activities. If used on `step()` or `evaluator()` it will apply only to that underlying activity. If changed in both places, the end value will be a merge between the initial values, workflow values and the step values.
+
+  Order of precedence
+  `step options > workflow options > default options`
+
 ## Developing
 
 To develop workflows you need the code, which will be called the worker, the API and the engine (Temporal).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -42,6 +42,7 @@
     "#utils": "./src/utils.js",
     "#tracing": "./src/tracing/internal_interface.js",
     "#async_storage": "./src/async_storage.js",
+    "#temporal_options": "./src/temporal_options.js",
     "#internal_activities": "./src/internal_activities/index.js"
   }
 }

package/src/consts.js

@@ -1,6 +1,8 @@
 export const ACTIVITY_SEND_WEBHOOK = '__internal#sendWebhook';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
+export const SHARED_STEP_PREFIX = '__shared#';
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
+export const ACTIVITY_OPTIONS_FILENAME = '__activity_options.js';
 export const WORKFLOW_CATALOG = '$catalog';
 export const ComponentType = {
   EVALUATOR: 'evaluator',

package/src/index.d.ts

@@ -1,5 +1,6 @@
 // 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
 export { z } from 'zod';
@@ -19,6 +20,17 @@ export { z } from 'zod';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyZodSchema = z.ZodType<any, any, any>;
 
+/**
+ * Activity retry options accepted by step/evaluator/workflow definitions.
+ * Uses Temporal's ActivityOptions['retry'] type.
+ */
+export type Options = { retry?: ActivityOptions['retry'] };
+
+/**
+ * @typedef {object} Options
+ * @property {import('@temporalio/workflow').ActivityOptions['retry']} [retry]
+ */
+
 /*
 ╭─────────╮
 │ S T E P │╮
@@ -43,6 +55,7 @@ type AnyZodSchema = z.ZodType<any, any, any>;
  * @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<
@@ -54,6 +67,7 @@ export async function step<
   inputSchema: InputSchema;
   outputSchema: OutputSchema;
   fn: ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
+  options?: Options;
 } ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
 
 /**
@@ -64,6 +78,7 @@ export async function step<
  * @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>`
  */
 export async function step<
@@ -73,6 +88,7 @@ export async function step<
   description?: string;
   inputSchema: InputSchema;
   fn: ( input: z.infer<InputSchema> ) => Promise<void>;
+  options?: Options;
 } ): ( input: z.infer<InputSchema> ) => Promise<void>;
 
 /**
@@ -83,6 +99,7 @@ export async function step<
  * @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>>`
  */
 export async function step<
@@ -92,6 +109,7 @@ export async function step<
   description?: string;
   outputSchema: OutputSchema;
   fn: () => Promise<z.infer<OutputSchema>>;
+  options?: Options;
 } ): () => Promise<z.infer<OutputSchema>>;
 
 /**
@@ -101,12 +119,14 @@ export async function step<
  * @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>`
  */
 export async function step( options: {
   name: string;
   description?: string;
   fn: () => Promise<void>;
+  options?: Options;
 } ): () => Promise<void>;
 
 /*
@@ -132,6 +152,7 @@ export async function step( options: {
  * @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>>`
  */
 export function workflow<
@@ -142,7 +163,8 @@ export function workflow<
   description?: string,
   inputSchema: InputSchema,
   outputSchema: OutputSchema,
-  fn: ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>
+  fn: ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>,
+  options?: Options
 } ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
 
 /**
@@ -153,6 +175,7 @@ export function workflow<
  * @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>`
  */
 export function workflow<
@@ -161,7 +184,8 @@ export function workflow<
   name: string,
   description?: string,
   inputSchema: InputSchema,
-  fn: ( input: z.infer<InputSchema> ) => Promise<void>
+  fn: ( input: z.infer<InputSchema> ) => Promise<void>,
+  options?: Options
 } ): ( input: z.infer<InputSchema> ) => Promise<void>;
 
 /**
@@ -172,6 +196,7 @@ export function workflow<
  * @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>>`
  */
 export function workflow<
@@ -180,7 +205,8 @@ export function workflow<
   name: string,
   description?: string,
   outputSchema: OutputSchema,
-  fn: () => Promise<z.infer<OutputSchema>>
+  fn: () => Promise<z.infer<OutputSchema>>,
+  options?: Options
 } ): () => Promise<z.infer<OutputSchema>>;
 
 /**
@@ -190,12 +216,14 @@ export function workflow<
  * @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>`
  */
 export function workflow( options : {
   name: string,
   description?: string,
-  fn: () => Promise<void>
+  fn: () => Promise<void>,
+  options?: Options
 } ): () => Promise<void>;
 
 /*
@@ -309,6 +337,7 @@ export class EvaluationBooleanResult extends EvaluationResult {
  * @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>>`
  */
 export async function evaluator<
@@ -319,6 +348,7 @@ export async function evaluator<
   description?: string;
   inputSchema: InputSchema;
   fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
+  options?: Options;
 } ): ( input: z.infer<InputSchema> ) => Promise<Result>;
 
 /**
@@ -329,6 +359,7 @@ export async function evaluator<
  * @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>>`
  */
 export async function evaluator<
@@ -338,6 +369,7 @@ export async function evaluator<
   name: string;
   description?: string;
   fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
+  options?: Options;
 } ): ( input: z.infer<InputSchema> ) => Promise<Result>;
 
 /*

package/src/interface/evaluator.js

@@ -1,6 +1,6 @@
-import { setMetadata } from './metadata.js';
 import { validateEvaluator } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
+import { setMetadata } from '#utils';
 import { ValidationError } from '#errors';
 import { ComponentType } from '#consts';
 import * as z from 'zod';
@@ -130,8 +130,8 @@ export class EvaluationNumberResult extends EvaluationResult {
   }
 };
 
-export function evaluator( { name, description, inputSchema, fn } ) {
-  validateEvaluator( { name, description, inputSchema, fn } );
+export function evaluator( { name, description, inputSchema, fn, options } ) {
+  validateEvaluator( { name, description, inputSchema, fn, options } );
 
   const wrapper = async input => {
     validateWithSchema( inputSchema, input, `Evaluator ${name} input` );
@@ -145,6 +145,6 @@ export function evaluator( { name, description, inputSchema, fn } ) {
     return output;
   };
 
-  setMetadata( wrapper, { name, description, inputSchema, type: ComponentType.EVALUATOR } );
+  setMetadata( wrapper, { name, description, inputSchema, type: ComponentType.EVALUATOR, options } );
   return wrapper;
 };

package/src/interface/step.js

@@ -1,10 +1,10 @@
-import { setMetadata } from './metadata.js';
+import { setMetadata } from '#utils';
 import { validateStep } from './validations/static.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 } );
+export function step( { name, description, inputSchema, outputSchema, fn, options } ) {
+  validateStep( { name, description, inputSchema, outputSchema, fn, options } );
 
   const wrapper = async input => {
     validateWithSchema( inputSchema, input, `Step ${name} input` );
@@ -16,6 +16,6 @@ export function step( { name, description, inputSchema, outputSchema, fn } ) {
     return output;
   };
 
-  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.STEP } );
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.STEP, options } );
   return wrapper;
 };

package/src/interface/validations/static.js

@@ -17,12 +17,26 @@ const refineSchema = ( value, ctx ) => {
   } );
 };
 
-const stepAndWorkflowSchema = z.object( {
+export const durationStringSchema = z.string().regex(
+  /^(\d+)(ms|s|m|h|d)$/,
+  'Expected duration like "500ms", "10s", "5m", "2h", or "1d"'
+);
+
+const stepAndWorkflowSchema = z.strictObject( {
   name: z.string().regex( /^[a-z_][a-z0-9_]*$/i ),
   description: z.string().optional(),
   inputSchema: z.any().optional().superRefine( refineSchema ),
   outputSchema: z.any().optional().superRefine( refineSchema ),
-  fn: z.function()
+  fn: z.function(),
+  options: z.strictObject( {
+    retry: z.strictObject( {
+      initialInterval: durationStringSchema.optional(),
+      backoffCoefficient: z.number().gte( 1 ).optional(),
+      maximumInterval: durationStringSchema.optional(),
+      maximumAttempts: z.number().gte( 1 ).int().optional(),
+      nonRetryableErrorTypes: z.array( z.string() ).optional()
+    } ).optional()
+  } ).optional()
 } );
 
 const evaluatorSchema = stepAndWorkflowSchema.omit( { outputSchema: true } );

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

@@ -65,6 +65,26 @@ describe( 'interface/validator', () => {
       const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at fn' );
       expect( () => validateStep( { ...validArgs, fn: 'not-fn' } ) ).toThrow( error );
     } );
+
+    it( 'passes with options.retry (second-level options)', () => {
+      const args = {
+        ...validArgs,
+        options: {
+          retry: {
+            initialInterval: '1s',
+            backoffCoefficient: 2,
+            maximumInterval: '10s',
+            maximumAttempts: 3,
+            nonRetryableErrorTypes: [ 'SomeError' ]
+          }
+        }
+      };
+      expect( () => validateStep( args ) ).not.toThrow();
+    } );
+
+    it( 'rejects unknown top-level keys due to strictObject', () => {
+      expect( () => validateStep( { ...validArgs, extra: 123 } ) ).toThrow( StaticValidationError );
+    } );
   } );
 
   describe( 'validateWorkflow', () => {

package/src/interface/workflow.js

@@ -1,27 +1,29 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { proxyActivities, inWorkflowContext, executeChild, workflowInfo } from '@temporalio/workflow';
 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 { SHARED_STEP_PREFIX } from '#consts';
+import { mergeActivityOptions, setMetadata } from '#utils';
+import { FatalError, ValidationError } from '#errors';
 
-const temporalActivityConfigs = {
-  startToCloseTimeout: '20 minute',
+const defaultActivityOptions = {
+  startToCloseTimeout: '20m',
   retry: {
     initialInterval: '10s',
     backoffCoefficient: 2.0,
-    maximumInterval: '2 minutes',
+    maximumInterval: '2m',
     maximumAttempts: 3,
     nonRetryableErrorTypes: [ ValidationError.name, FatalError.name ]
   }
 };
 
-export function workflow( { name, description, inputSchema, outputSchema, fn } ) {
-  validateWorkflow( { name, description, inputSchema, outputSchema, fn } );
+export function workflow( { name, description, inputSchema, outputSchema, fn, options } ) {
+  validateWorkflow( { name, description, inputSchema, outputSchema, fn, options } );
   const workflowPath = getInvocationDir();
 
-  const steps = proxyActivities( temporalActivityConfigs );
+  const activityOptions = mergeActivityOptions( defaultActivityOptions, options );
+  const steps = proxyActivities( activityOptions );
 
   const wrapper = async input => {
     validateWithSchema( inputSchema, input, `Workflow ${name} input` );
@@ -44,12 +46,16 @@ export function workflow( { name, description, inputSchema, outputSchema, fn } )
       startTime: startTime.getTime()
     };
 
-    Object.assign( memo, { executionContext } );
+    Object.assign( memo, {
+      executionContext,
+      activityOptions: memo.activityOptions ?? activityOptions // Also preserve the original activity options
+    } );
 
-    // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
+    // 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 ),
+      invokeStep: async ( stepName, input, options ) => steps[`${workflowPath}#${stepName}`]( input, options ),
+      invokeSharedStep: async ( stepName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${stepName}`]( input, options ),
+      invokeEvaluator: async ( evaluatorName, input, options ) => steps[`${workflowPath}#${evaluatorName}`]( input, options ),
 
       startWorkflow: async ( childName, input ) => {
         return executeChild( childName, { args: input ? [ input ] : [], memo: { executionContext, parentId: workflowId } } );

package/src/interface/zod_integration.spec.js

@@ -410,12 +410,12 @@ describe( 'Zod Schema Integration Tests', () => {
         inputSchema,
         fn: async input => {
           switch ( input.action ) {
-          case 'create':
-            return `Creating ${input.type}: ${input.name}`;
-          case 'delete':
-            return `Deleting item ${input.id}`;
-          default:
-            throw new Error( 'Unknown action' );
+            case 'create':
+              return `Creating ${input.type}: ${input.name}`;
+            case 'delete':
+              return `Deleting item ${input.id}`;
+            default:
+              throw new Error( 'Unknown action' );
           }
         }
       } );

package/src/internal_activities/index.js

@@ -1,5 +1,5 @@
 import { FatalError } from '#errors';
-import { setMetadata } from '../interface/metadata.js';
+import { setMetadata } from '#utils';
 import { ComponentType } from '#consts';
 
 /**

package/src/utils.js

@@ -1,3 +1,12 @@
+import { METADATA_ACCESS_SYMBOL } from '#consts';
+
+/**
+ * Node safe clone implementation that doesn't use global structuredClone()
+ * @param {object} v
+ * @returns {object}
+ */
+export const clone = v => JSON.parse( JSON.stringify( v ) );
+
 /**
  * Throw given error
  * @param {Error} e
@@ -6,3 +15,23 @@
 export const throws = e => {
   throw e;
 };
+
+/**
+ * Add metadata "values" property to a given object
+ * @param {object} target
+ * @param {object} values
+ * @returns
+ */
+export const setMetadata = ( target, values ) =>
+  Object.defineProperty( target, METADATA_ACCESS_SYMBOL, { value: values, writable: false, enumerable: false, configurable: false } );
+
+/**
+ * Merge two temporal activity options
+ * @param {import('@temporalio/workflow').ActivityOptions} base
+ * @param {import('@temporalio/workflow').ActivityOptions} ext
+ * @returns {import('@temporalio/workflow').ActivityOptions}
+ */
+export const mergeActivityOptions = ( base = {}, ext = {} ) =>
+  Object.entries( ext ).reduce( ( options, [ k, v ] ) =>
+    Object.assign( options, { [k]: typeof v === 'object' ? mergeActivityOptions( options[k], v ) : v } )
+  , clone( base ) );

package/src/utils.spec.js

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { clone, mergeActivityOptions } from './utils.js';
+
+describe( 'clone', () => {
+  it( 'produces a deep copy without shared references', () => {
+    const original = { a: 1, nested: { b: 2 } };
+    const copied = clone( original );
+
+    copied.nested.b = 3;
+
+    expect( original.nested.b ).toBe( 2 );
+    expect( copied.nested.b ).toBe( 3 );
+    expect( copied ).not.toBe( original );
+  } );
+} );
+
+describe( 'mergeActivityOptions', () => {
+  it( 'recursively merges nested objects', () => {
+    const base = {
+      taskQueue: 'q1',
+      retry: { maximumAttempts: 3, backoffCoefficient: 2 }
+    };
+    const ext = {
+      retry: { maximumAttempts: 5, initialInterval: '1s' }
+    };
+
+    const result = mergeActivityOptions( base, ext );
+
+    expect( result ).toEqual( {
+      taskQueue: 'q1',
+      retry: { maximumAttempts: 5, backoffCoefficient: 2, initialInterval: '1s' }
+    } );
+  } );
+
+  it( 'omitted properties in second do not overwrite first', () => {
+    const base = {
+      taskQueue: 'q2',
+      retry: { initialInterval: '2s', backoffCoefficient: 2 }
+    };
+    const ext = {
+      retry: { backoffCoefficient: 3 }
+    };
+
+    const result = mergeActivityOptions( base, ext );
+
+    expect( result.retry.initialInterval ).toBe( '2s' );
+    expect( result.retry.backoffCoefficient ).toBe( 3 );
+    expect( result.taskQueue ).toBe( 'q2' );
+  } );
+
+  it( 'handles omitted second argument by returning a clone', () => {
+    const base = { taskQueue: 'q3', retry: { maximumAttempts: 2 } };
+
+    const result = mergeActivityOptions( base );
+
+    expect( result ).toEqual( base );
+    expect( result ).not.toBe( base );
+  } );
+} );
+

package/src/worker/interceptors/workflow.js

@@ -1,6 +1,9 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { workflowInfo, proxySinks, ApplicationFailure } from '@temporalio/workflow';
 import { memoToHeaders } from '../sandboxed_utils.js';
+import { mergeActivityOptions } from '#utils';
+// this is a dynamic generated file with activity configs overwrites
+import stepOptions from '../temp/__activity_options.js';
 
 /*
   This is not an AI comment!
@@ -13,7 +16,13 @@ import { memoToHeaders } from '../sandboxed_utils.js';
 */
 class HeadersInjectionInterceptor {
   async scheduleActivity( input, next ) {
-    Object.assign( input.headers, memoToHeaders( workflowInfo().memo ) );
+    const memo = workflowInfo().memo ?? {};
+    Object.assign( input.headers, memoToHeaders( memo ) );
+    // apply per-invocation options passed as second argument by rewritten calls
+    const options = stepOptions[input.activityType];
+    if ( options ) {
+      input.options = mergeActivityOptions( memo.activityOptions, options );
+    }
     return next( input );
   }
 };

package/src/worker/loader.js

@@ -1,13 +1,30 @@
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { EOL } from 'node:os';
 import { fileURLToPath } from 'url';
 import { sendWebhook } from '#internal_activities';
-import { ACTIVITY_SEND_WEBHOOK, WORKFLOWS_INDEX_FILENAME, WORKFLOW_CATALOG } from '#consts';
 import { importComponents } from './loader_tools.js';
+import {
+  ACTIVITY_SEND_WEBHOOK,
+  ACTIVITY_OPTIONS_FILENAME,
+  SHARED_STEP_PREFIX,
+  WORKFLOWS_INDEX_FILENAME,
+  WORKFLOW_CATALOG
+} from '#consts';
 
 const __dirname = dirname( fileURLToPath( import.meta.url ) );
 
+/**
+ * Writes to file the activity options
+ *
+ * @param {object} optionsMap
+ */
+const writeActivityOptionsFile = map => {
+  const path = join( __dirname, 'temp', ACTIVITY_OPTIONS_FILENAME );
+  mkdirSync( dirname( path ), { recursive: true } );
+  writeFileSync( path, `export default ${JSON.stringify( map, undefined, 2 )};`, 'utf-8' );
+};
+
 /**
  * Builds a map of activities, where the key is their path and name and the value is the function
  *
@@ -16,11 +33,21 @@ const __dirname = dirname( fileURLToPath( import.meta.url ) );
  */
 export async function loadActivities( target ) {
   const activities = {};
-  for await ( const { fn, metadata, path } of importComponents( target, [ 'steps.js', 'evaluators.js' ] ) ) {
+  const activityOptionsMap = {};
+  for await ( const { fn, metadata, path } of importComponents( target, [ 'steps.js', 'evaluators.js', 'shared_steps.js' ] ) ) {
+    const isShared = basename( path ) === 'shared_steps.js';
+    const prefix = isShared ? SHARED_STEP_PREFIX : dirname( path );
+
     console.log( '[Core.Scanner]', 'Component loaded:', metadata.type, metadata.name, 'at', path );
-    activities[`${dirname( path )}#${metadata.name}`] = fn;
+    activities[`${prefix}#${metadata.name}`] = fn;
+    if ( metadata.options ) {
+      activityOptionsMap[`${prefix}#${metadata.name}`] = metadata.options;
+    }
   }
 
+  // writes down the activity option overrides
+  writeActivityOptionsFile( activityOptionsMap );
+
   // system activities
   activities[ACTIVITY_SEND_WEBHOOK] = sendWebhook;
   return activities;

package/src/worker/loader.spec.js

@@ -3,7 +3,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 vi.mock( '#consts', () => ( {
   ACTIVITY_SEND_WEBHOOK: '__internal#sendWebhook',
   WORKFLOWS_INDEX_FILENAME: '__workflows_entrypoint.js',
-  WORKFLOW_CATALOG: 'catalog'
+  WORKFLOW_CATALOG: 'catalog',
+  ACTIVITY_OPTIONS_FILENAME: '__activity_options.js'
 } ) );
 
 const sendWebhookMock = vi.fn();
@@ -26,16 +27,26 @@ describe( 'worker/loader', () => {
     vi.clearAllMocks();
   } );
 
-  it( 'loadActivities returns map including system activity', async () => {
+  it( 'loadActivities returns map including system activity and writes options file', async () => {
     const { loadActivities } = await import( './loader.js' );
 
     importComponentsMock.mockImplementationOnce( async function *() {
-      yield { fn: () => {}, metadata: { name: 'Act1' }, path: '/a/steps.js' };
+      yield { fn: () => {}, metadata: { name: 'Act1', options: { retry: { maximumAttempts: 3 } } }, path: '/a/steps.js' };
     } );
 
     const activities = await loadActivities( '/root' );
     expect( activities['/a#Act1'] ).toBeTypeOf( 'function' );
     expect( activities['__internal#sendWebhook'] ).toBe( sendWebhookMock );
+
+    // options file written with the collected map
+    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
+    const [ writtenPath, contents ] = writeFileSyncMock.mock.calls[0];
+    expect( writtenPath ).toMatch( /temp\/__activity_options\.js$/ );
+    expect( contents ).toContain( 'export default' );
+    expect( JSON.parse( contents.replace( /^export default\s*/, '' ).replace( /;\s*$/, '' ) ) ).toEqual( {
+      '/a#Act1': { retry: { maximumAttempts: 3 } }
+    } );
+    expect( mkdirSyncMock ).toHaveBeenCalled();
   } );
 
   it( 'loadWorkflows returns array of workflows with metadata', async () => {

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

@@ -3,9 +3,11 @@ import {
   buildWorkflowNameMap,
   getLocalNameFromDestructuredProperty,
   isEvaluatorsPath,
+  isSharedStepsPath,
   isStepsPath,
   isWorkflowPath,
   buildStepsNameMap,
+  buildSharedStepsNameMap,
   buildEvaluatorsNameMap,
   toAbsolutePath
 } from './tools.js';
@@ -36,8 +38,9 @@ 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, evaluatorsNameCache } ) {
+export default function collectTargetImports( ast, fileDir, { stepsNameCache, workflowNameCache, evaluatorsNameCache, sharedStepsNameCache } ) {
   const stepImports = [];
+  const sharedStepImports = [];
   const flowImports = [];
   const evaluatorImports = [];
 
@@ -45,33 +48,31 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
     ImportDeclaration: path => {
       const src = path.node.source.value;
       // Ignore other imports
-      if ( !isStepsPath( src ) && !isWorkflowPath( src ) && !isEvaluatorsPath( src ) ) {
+      if ( !isStepsPath( src ) && !isSharedStepsPath( src ) && !isWorkflowPath( src ) && !isEvaluatorsPath( src ) ) {
         return;
       }
 
       const absolutePath = toAbsolutePath( fileDir, src );
-      if ( isStepsPath( src ) ) {
-        const nameMap = buildStepsNameMap( absolutePath, stepsNameCache );
-        for ( const s of path.node.specifiers.filter( s => isImportSpecifier( s ) ) ) {
-          const importedName = s.imported.name;
-          const localName = s.local.name;
-          const stepName = nameMap.get( importedName );
-          if ( stepName ) {
-            stepImports.push( { localName, stepName } );
-          }
+      const collectNamedImports = ( match, buildMapFn, cache, targetArr, valueKey ) => {
+        if ( !match ) {
+          return;
         }
-      }
-      if ( isEvaluatorsPath( src ) ) {
-        const nameMap = buildEvaluatorsNameMap( absolutePath, evaluatorsNameCache );
+        const nameMap = buildMapFn( absolutePath, cache );
         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 } );
+          const value = nameMap.get( importedName );
+          if ( value ) {
+            const entry = { localName };
+            entry[valueKey] = value;
+            targetArr.push( entry );
           }
         }
-      }
+      };
+
+      collectNamedImports( isStepsPath( src ), buildStepsNameMap, stepsNameCache, stepImports, 'stepName' );
+      collectNamedImports( isSharedStepsPath( src ), buildSharedStepsNameMap, sharedStepsNameCache, sharedStepImports, 'stepName' );
+      collectNamedImports( isEvaluatorsPath( src ), buildEvaluatorsNameMap, evaluatorsNameCache, evaluatorImports, 'evaluatorName' );
       if ( isWorkflowPath( src ) ) {
         const { named, default: defName } = buildWorkflowNameMap( absolutePath, workflowNameCache );
         for ( const s of path.node.specifiers ) {
@@ -108,7 +109,7 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
 
       const req = firstArgument.value;
       // Must be steps/workflows module
-      if ( !isStepsPath( req ) && !isWorkflowPath( req ) && !isEvaluatorsPath( req ) ) {
+      if ( !isStepsPath( req ) && !isSharedStepsPath( req ) && !isWorkflowPath( req ) && !isEvaluatorsPath( req ) ) {
         return;
       }
 
@@ -130,6 +131,23 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
         } else {
           path.remove();
         }
+      } else if ( isSharedStepsPath( req ) && isObjectPattern( path.node.id ) ) {
+        const nameMap = buildSharedStepsNameMap( absolutePath, sharedStepsNameCache ?? stepsNameCache );
+        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 stepName = nameMap.get( importedName );
+            if ( stepName ) {
+              sharedStepImports.push( { localName, stepName } );
+            }
+          }
+        }
+        if ( isVariableDeclaration( path.parent ) && path.parent.declarations.length === 1 ) {
+          path.parentPath.remove();
+        } 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 ) ) ) {
@@ -160,5 +178,5 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
     }
   } );
 
-  return { stepImports, evaluatorImports, flowImports };
+  return { stepImports, sharedStepImports, evaluatorImports, flowImports };
 };

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 sharedStepsNameCache = new Map(); // path -> Map<exported, stepName> (shared)
 const evaluatorsNameCache = new Map(); // path -> Map<exported, evaluatorName>
 const workflowNameCache = new Map(); // path -> { default?: name, named: Map<exported, flowName> }
 
@@ -26,20 +27,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, evaluatorsNameCache, workflowNameCache };
+  const cache = { stepsNameCache, sharedStepsNameCache, evaluatorsNameCache, workflowNameCache };
 
   try {
     const filename = this.resourcePath;
     const ast = parse( String( source ), filename );
     const fileDir = dirname( filename );
-    const { stepImports, evaluatorImports, flowImports } = collectTargetImports( ast, fileDir, cache );
+    const { stepImports, sharedStepImports, evaluatorImports, flowImports } = collectTargetImports( ast, fileDir, cache );
 
     // No imports
-    if ( [].concat( stepImports, evaluatorImports, flowImports ).length === 0 ) {
+    if ( [].concat( stepImports, sharedStepImports, evaluatorImports, flowImports ).length === 0 ) {
       return callback( null, source, inputMap );
     }
 
-    const rewrote = rewriteFnBodies( { ast, stepImports, evaluatorImports, flowImports } );
+    const rewrote = rewriteFnBodies( { ast, stepImports, sharedStepImports, evaluatorImports, flowImports } );
     // No edits performed
     if ( !rewrote ) {
       return callback( null, source, inputMap );

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

@@ -51,6 +51,54 @@ describe( 'workflows_rewriter Webpack loader spec', () => {
     rmSync( dir, { recursive: true, force: true } );
   } );
 
+  it( 'rewrites ESM shared_steps imports to invokeSharedStep', async () => {
+    const dir = mkdtempSync( join( tmpdir(), 'ast-loader-esm-shared-' ) );
+    writeFileSync( join( dir, 'shared_steps.js' ), 'export const SharedA = step({ name: \'shared.a\' })\n' );
+
+    const source = [
+      'import { SharedA } from \'./shared_steps.js\';',
+      '',
+      'const obj = {',
+      '  fn: async (x) => {',
+      '    SharedA(1);',
+      '  }',
+      '}',
+      ''
+    ].join( '\n' );
+
+    const { code } = await runLoader( source, join( dir, 'file.js' ) );
+
+    expect( code ).not.toMatch( /from '\.\/shared_steps\.js'/ );
+    expect( code ).toMatch( /fn:\s*async function \(x\)/ );
+    expect( code ).toMatch( /this\.invokeSharedStep\('shared\.a',\s*1\)/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'rewrites CJS shared_steps requires to invokeSharedStep', async () => {
+    const dir = mkdtempSync( join( tmpdir(), 'ast-loader-cjs-shared-' ) );
+    writeFileSync( join( dir, 'shared_steps.js' ), 'export const SharedB = step({ name: \'shared.b\' })\n' );
+
+    const source = [
+      'const { SharedB } = require(\'./shared_steps.js\');',
+      '',
+      'const obj = {',
+      '  fn: async (y) => {',
+      '    SharedB();',
+      '  }',
+      '}',
+      ''
+    ].join( '\n' );
+
+    const { code } = await runLoader( source, join( dir, 'file.js' ) );
+
+    expect( code ).not.toMatch( /require\('\.\/shared_steps\.js'\)/ );
+    expect( code ).toMatch( /fn:\s*async function \(y\)/ );
+    expect( code ).toMatch( /this\.invokeSharedStep\('shared\.b'\)/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
   it( 'rewrites CJS requires and converts fn arrow to function', async () => {
     const dir = mkdtempSync( join( tmpdir(), 'ast-loader-cjs-' ) );
     writeFileSync( join( dir, 'steps.js' ), 'export const StepB = step({ name: \'step.b\' })\n' );

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

@@ -18,11 +18,12 @@ const traverse = traverseModule.default ?? traverseModule;
  * @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,stepName:string}>} params.sharedStepImports - Shared 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, evaluatorImports, flowImports } ) {
+export default function rewriteFnBodies( { ast, stepImports, sharedStepImports = [], evaluatorImports, flowImports } ) {
   const state = { rewrote: false };
   traverse( ast, {
     ObjectProperty: path => {
@@ -51,25 +52,20 @@ export default function rewriteFnBodies( { ast, stepImports, evaluatorImports, f
           if ( !isIdentifier( callee ) ) {
             return;
           } // Skip: complex callee not supported
-          const step = stepImports.find( x => x.localName === callee.name );
-          if ( step ) {
-            const args = cPath.node.arguments;
-            cPath.replaceWith( createThisMethodCall( 'invokeStep', step.stepName, args ) );
-            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;
-            cPath.replaceWith( createThisMethodCall( 'startWorkflow', flow.workflowName, args ) );
-            state.rewrote = true;
+          const descriptors = [
+            { list: stepImports, method: 'invokeStep', key: 'stepName' },
+            { list: sharedStepImports, method: 'invokeSharedStep', key: 'stepName' },
+            { list: evaluatorImports, method: 'invokeEvaluator', key: 'evaluatorName' },
+            { list: flowImports, method: 'startWorkflow', key: 'workflowName' }
+          ];
+          for ( const { list, method, key } of descriptors ) {
+            const found = list.find( x => x.localName === callee.name );
+            if ( found ) {
+              const args = cPath.node.arguments;
+              cPath.replaceWith( createThisMethodCall( method, found[key], args ) );
+              state.rewrote = true;
+              return;
+            }
           }
         }
       } );

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 shared_steps.js.
+ * @param {string} value - Module path or request string.
+ * @returns {boolean} True if it matches shared_steps.js.
+ */
+export const isSharedStepsPath = value => /(^|\/)shared_steps\.js$/.test( value );
+
 /**
  * Check if a module specifier or request string points to evaluators.js.
  * @param {string} value - Module path or request string.
@@ -215,6 +222,22 @@ export const buildStepsNameMap = ( path, cache ) => buildComponentNameMap( {
   invalidMessagePrefix: 'Invalid step name in'
 } );
 
+/**
+ * Build a map from exported shared step identifier to declared step name.
+ * Parses `shared_steps.js` for `export const X = step({ name: '...' })`.
+ * Uses the same factory as regular steps.
+ *
+ * @param {string} path - Absolute path to the shared steps module file.
+ * @param {Map<string, Map<string,string>>} cache - Cache of computed name maps.
+ * @returns {Map<string,string>} Exported identifier -> step name.
+ */
+export const buildSharedStepsNameMap = ( path, cache ) => buildComponentNameMap( {
+  path,
+  cache,
+  calleeName: 'step',
+  invalidMessagePrefix: 'Invalid shared step name in'
+} );
+
 /**
  * Build a map from exported evaluator identifier to declared evaluator name.
  * Parses `evaluators.js` for `export const X = evaluator({ name: '...' })`.

package/src/interface/metadata.js

@@ -1,4 +0,0 @@
-import { METADATA_ACCESS_SYMBOL } from '#consts';
-
-export const setMetadata = ( target, values ) =>
-  Object.defineProperty( target, METADATA_ACCESS_SYMBOL, { value: values, writable: false, enumerable: false, configurable: false } );