@output.ai/core 0.1.1 → 0.1.3

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.3",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -11,6 +11,10 @@
     "./tracing": {
       "types": "./src/tracing/index.d.ts",
       "import": "./src/tracing/index.js"
+    },
+    "./utils": {
+      "types": "./src/utils/index.d.ts",
+      "import": "./src/utils/index.js"
     }
   },
   "files": [
@@ -33,15 +37,17 @@
     "@temporalio/worker": "1.13.1",
     "@temporalio/workflow": "1.13.1",
     "redis": "5.8.3",
+    "stacktrace-parser": "0.1.11",
     "zod": "4.1.12"
   },
   "license": "UNLICENSED",
   "imports": {
     "#consts": "./src/consts.js",
     "#errors": "./src/errors.js",
-    "#utils": "./src/utils.js",
+    "#utils": "./src/utils/index.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,28 @@
 // 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, resolveInvocationDir, 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 } );
-  const workflowPath = getInvocationDir();
+export function workflow( { name, description, inputSchema, outputSchema, fn, options } ) {
+  validateWorkflow( { name, description, inputSchema, outputSchema, fn, options } );
+  const workflowPath = resolveInvocationDir();
 
-  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 +45,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/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Return the directory of the file invoking the code that called this function
+ * Excludes `@output.ai/core`, node, and other internal paths
+ */
+export function resolveInvocationDir(): string;
+
+/**
+ * Node safe clone implementation that doesn't use global structuredClone()
+ * @param {object} v
+ * @returns {object}
+ */
+export function clone( v: object ): object;
+
+/**
+ * Throw given error
+ * @param {Error} e
+ * @throws {e}
+ */
+export function throws( e: Error ): void;
+
+/**
+ * Add metadata "values" property to a given object
+ * @param {object} target
+ * @param {object} values
+ * @returns
+ */
+export function setMetadata( target: object, values: object ): void;
+
+/**
+ * Merge two temporal activity options
+ */
+export function mergeActivityOptions(
+  base?: import( '@temporalio/workflow' ).ActivityOptions,
+  ext?: import( '@temporalio/workflow' ).ActivityOptions
+): import( '@temporalio/workflow' ).ActivityOptions;

package/src/utils/index.js

@@ -0,0 +1,2 @@
+export { default as resolveInvocationDir } from './resolve_invocation_dir.js';
+export * from './utils.js';

package/src/utils/resolve_invocation_dir.js

@@ -0,0 +1,27 @@
+import * as stackTraceParser from 'stacktrace-parser';
+
+// OS separator, but in a deterministic way, allowing this to work in Temporal's sandbox
+// This avoids importing from node:path
+const SEP = new Error().stack.includes( '/' ) ? '/' : '\\';
+const ignorePaths = [
+  `${SEP}node_modules${SEP}`,
+  `${SEP}app${SEP}sdk${SEP}`,
+  `node:internal${SEP}`,
+  'evalmachine.',
+  `webpack${SEP}bootstrap`
+];
+
+/**
+ * Return the directory of the file invoking the code that called this function
+ * Excludes some internal paths and the sdk itself
+ */
+export default () => {
+  const stack = new Error().stack;
+  const lines = stackTraceParser.parse( stack );
+
+  const frame = lines.find( l => !ignorePaths.some( p => l.file.includes( p ) ) );
+  if ( !frame ) {
+    throw new Error( `Invocation dir resolution via stack trace failed. Stack: ${stack}` );
+  }
+  return frame.file.replace( 'file://', '' ).split( SEP ).slice( 0, -1 ).join( SEP );
+};