@outputai/core 0.8.1-next.e92f632.0 → 0.8.2-dev.e78f6b4.0

package/src/internal_activities/index.js

@@ -1,9 +1,10 @@
 import { FatalError } from '#errors';
 import { fetch } from 'undici';
-import { setMetadata, serializeFetchResponse, serializeBodyAndInferContentType } from '#utils';
-import { ComponentType } from '#consts';
+import { serializeFetchResponse, serializeBodyAndInferContentType } from '#helpers/fetch';
 import { createChildLogger } from '#logger';
 import { getDestinations } from '#tracing';
+import { createInternalStep } from '#helpers/component';
+import { ACTIVITY_GET_TRACE_DESTINATIONS, ACTIVITY_SEND_HTTP_REQUEST } from '#consts';
 
 const log = createChildLogger( 'HttpClient' );
 
@@ -19,41 +20,42 @@ const log = createChildLogger( 'HttpClient' );
  * @returns {object} The serialized HTTP response
  * @throws {FatalError}
  */
-export const sendHttpRequest = async ( { url, method, payload = undefined, headers = undefined, timeout = 30_000 } ) => {
-  const args = {
-    method,
-    headers: new Headers( headers ?? {} ),
-    signal: AbortSignal.timeout( timeout )
-  };
+export const sendHttpRequest = createInternalStep( {
+  name: ACTIVITY_SEND_HTTP_REQUEST,
+  handler: async ( { url, method, payload = undefined, headers = undefined, timeout = 30_000 } ) => {
+    const args = {
+      method,
+      headers: new Headers( headers ?? {} ),
+      signal: AbortSignal.timeout( timeout )
+    };
 
-  const methodsWithBody = [ 'DELETE', 'PATCH', 'POST', 'PUT', 'OPTIONS' ];
-  const hasBodyPayload = ![ undefined, null ].includes( payload );
-  if ( methodsWithBody.includes( method ) && hasBodyPayload ) {
-    const { body, contentType } = serializeBodyAndInferContentType( payload );
-    if ( contentType && !args.headers.has( 'content-type' ) ) {
-      args.headers.set( 'Content-Type', contentType );
-    }
-    Object.assign( args, { body } );
-  };
-
-  const response = await ( async () => {
-    try {
-      return await fetch( url, args );
-    } catch ( e ) {
-      throw new FatalError( `${method} ${url} ${e.cause ?? e.message}` );
-    }
-  } )();
+    const methodsWithBody = [ 'DELETE', 'PATCH', 'POST', 'PUT', 'OPTIONS' ];
+    const hasBodyPayload = ![ undefined, null ].includes( payload );
+    if ( methodsWithBody.includes( method ) && hasBodyPayload ) {
+      const { body, contentType } = serializeBodyAndInferContentType( payload );
+      if ( contentType && !args.headers.has( 'content-type' ) ) {
+        args.headers.set( 'Content-Type', contentType );
+      }
+      Object.assign( args, { body } );
+    };
 
-  log.info( 'HTTP request completed', { url, method, status: response.status, statusText: response.statusText } );
+    const response = await ( async () => {
+      try {
+        return await fetch( url, args );
+      } catch ( e ) {
+        throw new FatalError( `${method} ${url} ${e.cause ?? e.message}` );
+      }
+    } )();
 
-  if ( !response.ok ) {
-    throw new FatalError( `${method} ${url} ${response.status}` );
-  }
+    log.info( 'HTTP request completed', { url, method, status: response.status, statusText: response.statusText } );
 
-  return serializeFetchResponse( response );
-};
+    if ( !response.ok ) {
+      throw new FatalError( `${method} ${url} ${response.status}` );
+    }
 
-setMetadata( sendHttpRequest, { type: ComponentType.INTERNAL_STEP } );
+    return serializeFetchResponse( response );
+  }
+} );
 
 /**
  * Invokes a trace method that resolves all trace output paths based on the traceInfo
@@ -61,6 +63,7 @@ setMetadata( sendHttpRequest, { type: ComponentType.INTERNAL_STEP } );
  * @param {object} traceInfo
  * @returns {object} Information about enabled destinations
  */
-export const getTraceDestinations = traceInfo => getDestinations( traceInfo );
-
-setMetadata( getTraceDestinations, { type: ComponentType.INTERNAL_STEP } );
+export const getTraceDestinations = createInternalStep( {
+  name: ACTIVITY_GET_TRACE_DESTINATIONS,
+  handler: traceInfo => getDestinations( traceInfo )
+} );

package/src/internal_activities/index.spec.js

@@ -1,10 +1,12 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { MockAgent, setGlobalDispatcher } from 'undici';
 import { FatalError } from '#errors';
-import { serializeBodyAndInferContentType, serializeFetchResponse } from '#utils';
+import { ACTIVITY_GET_TRACE_DESTINATIONS, ACTIVITY_SEND_HTTP_REQUEST } from '#consts';
+import { serializeBodyAndInferContentType, serializeFetchResponse } from '#helpers/fetch';
 import { getTraceDestinations, sendHttpRequest } from './index.js';
 
 const getDestinationsMock = vi.hoisted( () => vi.fn() );
+const createInternalStepMock = vi.hoisted( () => vi.fn( ( { handler } ) => handler ) );
 
 vi.mock( '#tracing', () => ( {
   getDestinations: getDestinationsMock
@@ -15,9 +17,15 @@ vi.mock( '#logger', () => {
   return { createChildLogger: vi.fn( () => log ) };
 } );
 
-vi.mock( '#utils', () => ( {
-  setMetadata: vi.fn(),
-  isStringboolTrue: vi.fn( () => false ),
+vi.mock( '#helpers/component', () => ( {
+  createInternalStep: createInternalStepMock
+} ) );
+
+vi.mock( '#helpers/string', () => ( {
+  isStringboolTrue: vi.fn( () => false )
+} ) );
+
+vi.mock( '#helpers/fetch', () => ( {
   serializeBodyAndInferContentType: vi.fn(),
   serializeFetchResponse: vi.fn()
 } ) );
@@ -30,6 +38,21 @@ setGlobalDispatcher( mockAgent );
 const url = 'https://growthx.ai';
 const method = 'GET';
 
+describe( 'internal_activities component registration', () => {
+  it( 'creates internal step components for exported activities', () => {
+    expect( createInternalStepMock ).toHaveBeenNthCalledWith( 1, {
+      name: ACTIVITY_SEND_HTTP_REQUEST,
+      handler: expect.any( Function )
+    } );
+    expect( createInternalStepMock ).toHaveBeenNthCalledWith( 2, {
+      name: ACTIVITY_GET_TRACE_DESTINATIONS,
+      handler: expect.any( Function )
+    } );
+    expect( sendHttpRequest ).toBe( createInternalStepMock.mock.calls[0][0].handler );
+    expect( getTraceDestinations ).toBe( createInternalStepMock.mock.calls[1][0].handler );
+  } );
+} );
+
 describe( 'internal_activities/sendHttpRequest', () => {
   beforeEach( async () => {
     vi.restoreAllMocks();

package/src/logger/development.js

@@ -1,5 +1,5 @@
 import { format, transports } from 'winston';
-import { isPlainObject, shuffleArray } from '#utils';
+import { shuffleArray, isPlainObject } from '#helpers/object';
 
 /** Available colors enum */
 const Color = {
@@ -47,7 +47,7 @@ const getColor = v =>
   assignedColors.get( v ) ?? assignedColors.set( v, COLORS[assignedColors.size % COLORS.length] ).get( v );
 
 export const options = {
-  level: 'debug',
+  level: process.env.OUTPUT_LOG_LEVEL ?? 'debug',
   transports: [ new transports.Console() ],
   format: format.combine(
     format.colorize(),

package/src/logger/development.spec.js

@@ -1,9 +1,9 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 const LEVEL = Symbol.for( 'level' );
 const MESSAGE = Symbol.for( 'message' );
 
-vi.mock( '#utils', () => ( {
+vi.mock( '#helpers/object', () => ( {
   isPlainObject: v => Object.prototype.toString.call( v ) === '[object Object]',
   shuffleArray: v => v
 } ) );
@@ -14,6 +14,10 @@ const loadDevelopmentLogger = async () => {
 };
 
 describe( 'logger/development', () => {
+  afterEach( () => {
+    vi.unstubAllEnvs();
+  } );
+
   describe( 'formatJson', () => {
     it( 'formats nested plain objects and arrays', async () => {
       const { formatJson } = await loadDevelopmentLogger();
@@ -40,6 +44,19 @@ describe( 'logger/development', () => {
   } );
 
   describe( 'options.format', () => {
+    it( 'uses debug level by default', async () => {
+      const { options } = await loadDevelopmentLogger();
+
+      expect( options.level ).toBe( 'debug' );
+    } );
+
+    it( 'uses OUTPUT_LOG_LEVEL when configured', async () => {
+      vi.stubEnv( 'OUTPUT_LOG_LEVEL', 'http' );
+      const { options } = await loadDevelopmentLogger();
+
+      expect( options.level ).toBe( 'http' );
+    } );
+
     it( 'formats level, namespace, message, and metadata fields', async () => {
       const { options } = await loadDevelopmentLogger();
       const info = options.format.transform( {

package/src/logger/production.js

@@ -1,7 +1,7 @@
 import { transports, format } from 'winston';
 
 export const options = {
-  level: 'info',
+  level: process.env.OUTPUT_LOG_LEVEL ?? 'info',
   transports: [ new transports.Console() ],
   defaultMeta: {
     service: 'output-worker',

package/src/logger/production.spec.js

@@ -1,11 +1,21 @@
-import { describe, expect, it } from 'vitest';
-import { options } from './production.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 const LEVEL = Symbol.for( 'level' );
 const MESSAGE = Symbol.for( 'message' );
 
+const loadProductionLogger = async () => {
+  vi.resetModules();
+  return import( './production.js' );
+};
+
 describe( 'logger/production', () => {
-  it( 'uses info level and default production metadata', () => {
+  afterEach( () => {
+    vi.unstubAllEnvs();
+  } );
+
+  it( 'uses info level and default production metadata', async () => {
+    const { options } = await loadProductionLogger();
+
     expect( options.level ).toBe( 'info' );
     expect( options.defaultMeta ).toEqual( {
       service: 'output-worker',
@@ -13,7 +23,15 @@ describe( 'logger/production', () => {
     } );
   } );
 
-  it( 'formats logs as JSON with timestamp and metadata fields', () => {
+  it( 'uses OUTPUT_LOG_LEVEL when configured', async () => {
+    vi.stubEnv( 'OUTPUT_LOG_LEVEL', 'debug' );
+    const { options } = await loadProductionLogger();
+
+    expect( options.level ).toBe( 'debug' );
+  } );
+
+  it( 'formats logs as JSON with timestamp and metadata fields', async () => {
+    const { options } = await loadProductionLogger();
     const info = options.format.transform( {
       [LEVEL]: 'info',
       level: 'info',
@@ -33,7 +51,8 @@ describe( 'logger/production', () => {
     expect( output.timestamp ).toEqual( expect.stringMatching( /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}$/u ) );
   } );
 
-  it( 'includes error stack when formatting Error messages', () => {
+  it( 'includes error stack when formatting Error messages', async () => {
+    const { options } = await loadProductionLogger();
     const error = new Error( 'boom' );
     const info = options.format.transform( {
       [LEVEL]: 'error',

package/src/sdk/README.md

@@ -0,0 +1,47 @@
+## SDK integration API for Output packages
+
+**THESE MODULES ARE NOT PUBLIC. DO NOT IMPORT THEM ON YOUR PROJECT.**
+
+This folder contains integration helpers used by other Output SDK packages.
+
+The two subfolders represent a hard Temporal boundary. Code imported by
+workflow-bundled modules must only depend on `helpers`. Code that needs worker
+or activity runtime state belongs in `runtime`.
+
+Do not change these without reviewing call-sites.
+
+### `helpers`
+
+Helpers must be safe to import while Temporal workflows are bundled and executed
+in the workflow sandbox.
+
+Allowed:
+
+- Stateless functions and namespace objects.
+- Deterministic code with no runtime side effects at import time.
+- Imports from other sandbox-safe helper modules.
+- Small, dependency-free helpers for any deterministic computation that can run
+  without worker or activity state.
+
+Not allowed:
+
+- Access to activity context, async storage, sinks, tracing state, workers, or
+  clients.
+- Imports from `@temporalio/activity`, `@temporalio/worker`, or Node-only APIs
+  that cannot be bundled into workflow code.
+- Process, filesystem, network, clock, randomness, or environment access unless
+  the behavior is known to be safe and deterministic in the workflow sandbox.
+- Any import chain that reaches `runtime`.
+
+If a helper cannot satisfy these rules, put it in `runtime` instead.
+
+### `runtime`
+
+Runtime modules are for helpers that need Output or Temporal runtime state.
+
+Use `runtime` for activity-only integrations such as context lookup, event
+emission, tracing, async storage, worker state, sinks, and other behavior that is
+not safe inside workflow-bundled code.
+
+Runtime modules may depend on activity runtime APIs and internal state, but they
+must not be imported by workflow-safe code.

package/src/sdk/helpers/component_metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tools to extract data from Outputai Core Components metadata storage
+ */
+export declare const ComponentMetadata: {
+  /**
+   * Extract the name from a workflow(), step() or evaluator() return
+   * @param fn
+   * @returns
+   */
+  getName( fn: Function ): string | undefined;
+
+  /**
+   * Check if a function has metadata from workflow(), step() or evaluator()
+   * @param fn
+   */
+  has( fn: Function ): boolean;
+};

package/src/sdk/helpers/component_metadata.js

@@ -0,0 +1,6 @@
+import { METADATA_ACCESS_SYMBOL } from '#consts';
+
+export const ComponentMetadata = {
+  getName: fn => fn[METADATA_ACCESS_SYMBOL]?.name,
+  has: fn => !!fn[METADATA_ACCESS_SYMBOL]
+};

package/src/sdk/helpers/component_metadata.spec.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { METADATA_ACCESS_SYMBOL } from '#consts';
+import { ComponentMetadata } from './component_metadata.js';
+
+describe( 'ComponentMetadata', () => {
+  it( 'detects functions tagged with component metadata', () => {
+    const component = () => {};
+    Object.defineProperty( component, METADATA_ACCESS_SYMBOL, {
+      value: { name: 'my_component' }
+    } );
+
+    expect( ComponentMetadata.has( component ) ).toBe( true );
+  } );
+
+  it( 'returns the component metadata name', () => {
+    const component = () => {};
+    Object.defineProperty( component, METADATA_ACCESS_SYMBOL, {
+      value: { name: 'my_component' }
+    } );
+
+    expect( ComponentMetadata.getName( component ) ).toBe( 'my_component' );
+  } );
+
+  it( 'returns false and undefined for untagged functions', () => {
+    const fn = () => {};
+
+    expect( ComponentMetadata.has( fn ) ).toBe( false );
+    expect( ComponentMetadata.getName( fn ) ).toBeUndefined();
+  } );
+} );

package/src/sdk/helpers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * > [!WARNING]
+ * > **Internal use only.** Not part of the public API; may change without notice.
+ *
+ * These are stateless helpers for other SDK modules integration.
+ * They can be used while Temporal workflows are bundled.
+ *
+ * @packageDocumentation
+ */
+export * from './component_metadata.js';
+export * from './path.js';
+export * from './objects.js';

package/src/sdk/helpers/index.js

@@ -0,0 +1,3 @@
+export * from './component_metadata.js';
+export * from './path.js';
+export * from './objects.js';

package/src/sdk/helpers/objects.d.ts

@@ -0,0 +1,51 @@
+/** Tools to manipulate JS Objects */
+export declare const Objects: {
+  /**
+   * Node safe clone implementation that doesn't use global structuredClone().
+   *
+   * Returns a cloned version of the object.
+   *
+   * Only clones static properties. Getters become static properties.
+   *
+   * @param object
+   */
+  clone( object: object ): object,
+
+  /**
+   * Returns true if the value is a plain object:
+   * - `{}`
+   * - `new Object()`
+   * - `Object.create(null)`
+   *
+   * @param object - The value to check.
+   * @returns Whether the value is a plain object.
+   */
+  isPlainObject( object: unknown ): boolean,
+
+  /**
+   * Creates a new object by merging object `b` onto object `a`, biased toward `b`:
+   * - Fields in `b` overwrite fields in `a`.
+   * - Fields in `b` that don't exist in `a` are created.
+   * - Fields in `a` that don't exist in `b` are left unchanged.
+   *
+   * @param a - The base object.
+   * @param b - The overriding object.
+   * @throws {Error} If either `a` or `b` is not a plain object.
+   * @returns A new merged object.
+   */
+  deepMerge( a: object, b: object | null | undefined ): object,
+
+  /**
+   * Creates a new object by merging object `b` onto object `a`, biased toward `b`:
+   * - Fields in `b` that don't exist in `a` are created.
+   * - Fields in `a` that don't exist in `b` are left unchanged.
+   * - Fields in `a` and `b` are passed as arguments to the resolve function (a,b) and its return assigns the new value.
+   *
+   * @param a - The base object.
+   * @param b - The overriding object.
+   * @param resolver - The resolver function.
+   * @throws {Error} If either `a` or `b` is not a plain object.
+   * @returns A new merged object.
+   */
+  deepMergeWithResolver( a: object, b: object | null | undefined, resolver: ( a: unknown, b: unknown ) => unknown ): object
+};

package/src/sdk/helpers/objects.js

@@ -0,0 +1,8 @@
+import { clone, deepMerge, deepMergeWithResolver, isPlainObject } from '#helpers/object';
+
+export const Objects = {
+  clone,
+  deepMerge,
+  deepMergeWithResolver,
+  isPlainObject
+};

package/src/sdk/helpers/objects.spec.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { Objects } from './objects.js';
+import { Objects as ObjectsFromIndex } from './index.js';
+import { clone, deepMerge, deepMergeWithResolver, isPlainObject } from '#helpers/object';
+
+describe( 'Objects', () => {
+  it( 'exports the same functions from the object helper module', () => {
+    expect( Objects ).toBe( ObjectsFromIndex );
+    expect( Objects ).toEqual( {
+      clone,
+      deepMerge,
+      deepMergeWithResolver,
+      isPlainObject
+    } );
+  } );
+} );

package/src/sdk/helpers/path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tools to interact with filesystem paths
+ */
+export declare const Path: {
+  /**
+   * Return the first immediate directory of the file invoking the code that called this function.
+   *
+   * Excludes `@outputai/core`, node, other internal paths, and any additional ignore paths.
+   */
+  resolveInvocationDir( additionalIgnorePaths?: string[] ): string
+};

package/src/sdk/helpers/path.js

@@ -0,0 +1,32 @@
+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 transformSeparators = path => path.replaceAll( '/', SEP );
+
+const defaultIgnorePaths = [
+  '/@outputai/core/',
+  '/@outputai/llm/',
+  '/@outputai/evals/',
+  '/sdk/core/',
+  '/sdk/llm/',
+  '/sdk/evals/',
+  'node:internal/',
+  'evalmachine.',
+  'webpack/bootstrap'
+];
+
+export const Path = {
+  resolveInvocationDir: ( additionalIgnorePaths = [] ) => {
+    const stack = new Error().stack;
+    const lines = stackTraceParser.parse( stack );
+    const ignorePaths = [ ...additionalIgnorePaths, ...defaultIgnorePaths ].map( transformSeparators );
+
+    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 );
+  }
+};

package/src/{utils/resolve_invocation_dir.spec.js → sdk/helpers/path.spec.js}

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from 'vitest';
-import resolveInvocationDir from './resolve_invocation_dir';
+import { Path } from './path.js';
 
 const OriginalError = Error;
 
@@ -10,7 +10,7 @@ describe( 'Resolve Invocation Dir', () => {
 
   it( 'Should detect the invocation dir from the tests workflow', () => {
     const stack = `Error
-    at resolveInvocationDir (file:///app/sdk/core/src/utils/resolve_invocation_dir.js)
+    at resolveInvocationDir (file:///app/sdk/core/src/sdk/helpers/path.js)
     at fn (file:///app/test_workflows/dist/simple/steps.js:8:21)
     at wrapper (file:///app/sdk/core/src/interface/step.js:12:26)
     at executeNextHandler (/app/node_modules/@temporalio/worker/lib/activity.js:99:54)
@@ -29,12 +29,12 @@ describe( 'Resolve Invocation Dir', () => {
       }
     };
 
-    expect( resolveInvocationDir() ).toBe( '/app/test_workflows/dist/simple' );
+    expect( Path.resolveInvocationDir() ).toBe( '/app/test_workflows/dist/simple' );
   } );
 
   it( 'Should detect the invocation dir from the sandbox environment at sdk/core', () => {
     const stack = `Error
-    at resolveInvocationDir (file:///app/sdk/core/src/utils/resolve_invocation_dir.js)
+    at resolveInvocationDir (file:///app/sdk/core/src/sdk/helpers/path.js)
     at workflow (file:///app/sdk/core/src/interface/workflow.js:25:16)
     at file:///app/test_workflows/dist/nested/workflow.js:4:16
     at ModuleJob.run (node:internal/modules/esm/module_job:365:25)
@@ -50,12 +50,12 @@ describe( 'Resolve Invocation Dir', () => {
       }
     };
 
-    expect( resolveInvocationDir() ).toBe( '/app/test_workflows/dist/nested' );
+    expect( Path.resolveInvocationDir() ).toBe( '/app/test_workflows/dist/nested' );
   } );
 
   it( 'Should detect the invocation dir from workflow loading at core', () => {
     const stack = `Error
-    at __WEBPACK_DEFAULT_EXPORT__ (/app/sdk/core/src/utils/resolve_invocation_dir.js:13:0)
+    at resolveInvocationDir (/app/sdk/core/src/sdk/helpers/path.js:21:0)
     at workflow (/app/sdk/core/src/interface/workflow.js:22:43)
     at ../../test_workflows/dist/nested/workflow.js (/app/test_workflows/dist/nested/workflow.js:4:24)
     at __webpack_require__ (webpack/bootstrap:19:0)
@@ -73,12 +73,12 @@ describe( 'Resolve Invocation Dir', () => {
       }
     };
 
-    expect( resolveInvocationDir() ).toBe( '/app/test_workflows/dist/nested' );
+    expect( Path.resolveInvocationDir() ).toBe( '/app/test_workflows/dist/nested' );
   } );
 
   it( 'Should detect the invocation dir from a workflow using core installed via NPM', () => {
     const stack = `Error
-    at resolveInvocationDir (file:///app/node_modules/@outputai/core/src/utils/resolve_invocation_dir.js)
+    at resolveInvocationDir (file:///app/node_modules/@outputai/core/src/sdk/helpers/path.js)
     at fn (file:///app/dist/simple/steps.js:8:21)
     at wrapper (file:///app/node_modules/@outputai/core/src/interface/step.js:12:26)
     at executeNextHandler (/app/node_modules/@temporalio/worker/lib/activity.js:99:54)
@@ -97,6 +97,6 @@ describe( 'Resolve Invocation Dir', () => {
       }
     };
 
-    expect( resolveInvocationDir() ).toBe( '/app/dist/simple' );
+    expect( Path.resolveInvocationDir() ).toBe( '/app/dist/simple' );
   } );
 } );

package/src/sdk/runtime/context.d.ts

@@ -0,0 +1,30 @@
+import type { Info } from '@temporalio/activity';
+
+/**
+ * Context object
+ */
+export type Context = {
+  /** Temporal info about the current activity */
+  activityInfo: Info,
+  /** Path of the workflow file */
+  workflowFilename: string
+};
+
+/**
+ * Tools to interact with Runtime context
+ */
+export declare const Context: {
+
+  /**
+   * Returns information about the current Temporal execution.
+   *
+   * Only available when called from within a step or evaluator (Temporal Activities) running in the Temporal runtime.
+   *
+   * @remarks
+   * - Returns `null` when not called inside a Temporal Activity (steps/evaluators);
+   * - Returns `null` when not called from within a running Temporal worker, like in unit tests environment;
+   *
+   * @returns The workflow context, or `null` if unavailable or incomplete.
+   */
+  getActivityContext(): Context | null;
+};

package/src/sdk/runtime/context.js

@@ -0,0 +1,15 @@
+import { Storage } from '#async_storage';
+
+export const Context = {
+  getActivityContext: () => {
+    const ctx = Storage.load();
+    if ( !ctx ) {
+      return null;
+    }
+
+    return {
+      workflowFilename: ctx.workflowFilename,
+      activityInfo: ctx.activityInfo
+    };
+  }
+};