@outputai/core 0.1.0

package/src/tracing/tools/build_trace_tree.spec.js

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest';
+import buildTraceTree from './build_trace_tree.js';
+
+describe( 'build_trace_tree', () => {
+  it( 'returns null when entries is empty', () => {
+    expect( buildTraceTree( [] ) ).toBeNull();
+  } );
+
+  it( 'sets root output with a fixed message when workflow has no end/error phase yet', () => {
+    const entries = [
+      { kind: 'workflow', id: 'wf', parentId: undefined, phase: 'start', name: 'wf', details: {}, timestamp: 1000 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result ).not.toBeNull();
+    expect( result.output ).toBe( '<<Workflow did not finish yet. If this workflows is supposed to have been completed already, \
+this can indicate it timed out or was interrupted.>>' );
+    expect( result.endedAt ).toBeNull();
+  } );
+
+  it( 'returns null when there is no root (all entries have parentId)', () => {
+    const entries = [
+      { id: 'a', parentId: 'x', phase: 'start', name: 'a', timestamp: 1 },
+      { id: 'b', parentId: 'a', phase: 'start', name: 'b', timestamp: 2 }
+    ];
+    expect( buildTraceTree( entries ) ).toBeNull();
+  } );
+
+  it( 'error phase sets error and endedAt on node', () => {
+    const entries = [
+      { kind: 'wf', id: 'r', parentId: undefined, phase: 'start', name: 'root', details: {}, timestamp: 100 },
+      { kind: 'step', id: 's', parentId: 'r', phase: 'start', name: 'step', details: {}, timestamp: 200 },
+      { id: 's', phase: 'error', details: { message: 'failed' }, timestamp: 300 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result ).not.toBeNull();
+    expect( result.children ).toHaveLength( 1 );
+    expect( result.children[0].error ).toEqual( { message: 'failed' } );
+    expect( result.children[0].endedAt ).toBe( 300 );
+  } );
+
+  it( 'builds a tree from workflow/step/IO entries with grouping and sorting', () => {
+    const entries = [
+      // workflow start
+      { kind: 'workflow', phase: 'start', name: 'wf', id: 'wf', parentId: undefined, details: { a: 1 }, timestamp: 1000 },
+      // evaluator start/stop
+      { kind: 'evaluator', phase: 'start', name: 'eval', id: 'eval', parentId: 'wf', details: { z: 0 }, timestamp: 1500 },
+      { id: 'eval', phase: 'end', details: { z: 1 }, timestamp: 1600 },
+      // step1 start
+      { kind: 'step', phase: 'start', name: 'step-1', id: 's1', parentId: 'wf', details: { x: 1 }, timestamp: 2000 },
+      // IO under step1
+      { kind: 'IO', phase: 'start', name: 'test-1', id: 'io1', parentId: 's1', details: { y: 2 }, timestamp: 2300 },
+      // step2 start
+      { kind: 'step', phase: 'start', name: 'step-2', id: 's2', parentId: 'wf', details: { x: 2 }, timestamp: 2400 },
+      // IO under step2
+      { kind: 'IO', phase: 'start', name: 'test-2', id: 'io2', parentId: 's2', details: { y: 3 }, timestamp: 2500 },
+      { id: 'io2', phase: 'end', details: { y: 4 }, timestamp: 2600 },
+      // IO under step1 ends
+      { id: 'io1', phase: 'end', details: { y: 5 }, timestamp: 2700 },
+      // step1 end
+      { id: 's1', phase: 'end', details: { done: true }, timestamp: 2800 },
+      // step2 end
+      { id: 's2', phase: 'end', details: { done: true }, timestamp: 2900 },
+      // workflow end
+      { id: 'wf', phase: 'end', details: { ok: true }, timestamp: 3000 }
+    ];
+
+    const result = buildTraceTree( entries );
+
+    const expected = {
+      id: 'wf',
+      kind: 'workflow',
+      name: 'wf',
+      startedAt: 1000,
+      endedAt: 3000,
+      input: { a: 1 },
+      output: { ok: true },
+      children: [
+        {
+          id: 'eval',
+          kind: 'evaluator',
+          name: 'eval',
+          startedAt: 1500,
+          endedAt: 1600,
+          input: { z: 0 },
+          output: { z: 1 },
+          children: []
+        },
+        {
+          id: 's1',
+          kind: 'step',
+          name: 'step-1',
+          startedAt: 2000,
+          endedAt: 2800,
+          input: { x: 1 },
+          output: { done: true },
+          children: [
+            {
+              id: 'io1',
+              kind: 'IO',
+              name: 'test-1',
+              startedAt: 2300,
+              endedAt: 2700,
+              input: { y: 2 },
+              output: { y: 5 },
+              children: []
+            }
+          ]
+        },
+        {
+          id: 's2',
+          kind: 'step',
+          name: 'step-2',
+          startedAt: 2400,
+          endedAt: 2900,
+          input: { x: 2 },
+          output: { done: true },
+          children: [
+            {
+              id: 'io2',
+              kind: 'IO',
+              name: 'test-2',
+              startedAt: 2500,
+              endedAt: 2600,
+              input: { y: 3 },
+              output: { y: 4 },
+              children: []
+            }
+          ]
+        }
+      ]
+    };
+
+    expect( result ).toMatchObject( expected );
+  } );
+} );

package/src/tracing/tools/utils.js

@@ -0,0 +1,21 @@
+/**
+ * @typedef {object} SerializedError
+ * @property {string} name - The error constructor name
+ * @property {string} message - The error message
+ * @property {string} stack - The error stack trace
+ */
+
+/**
+ * Serialize an error object.
+ *
+ * If it has ".cause", recursive serialize its cause until finally found an error without it.
+ *
+ * @param {Error} error
+ * @returns {SerializedError}
+ */
+export const serializeError = error =>
+  error.cause ? serializeError( error.cause ) : {
+    name: error.constructor.name,
+    message: error.message,
+    stack: error.stack
+  };

package/src/tracing/tools/utils.spec.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { serializeError } from './utils.js';
+
+describe( 'tracing/utils', () => {
+  it( 'serializeError unwraps causes and keeps message/stack', () => {
+    const inner = new Error( 'inner' );
+    const outer = new Error( 'outer', { cause: inner } );
+
+    const out = serializeError( outer );
+    expect( out.name ).toBe( 'Error' );
+    expect( out.message ).toBe( 'inner' );
+    expect( typeof out.stack ).toBe( 'string' );
+  } );
+} );

package/src/tracing/trace_engine.js

@@ -0,0 +1,97 @@
+import { Storage } from '#async_storage';
+import { EventEmitter } from 'node:events';
+import { serializeError } from './tools/utils.js';
+import { isStringboolTrue } from '#utils';
+import * as localProcessor from './processors/local/index.js';
+import * as s3Processor from './processors/s3/index.js';
+import { ComponentType } from '#consts';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Tracing' );
+
+const traceBus = new EventEmitter();
+const processors = [
+  {
+    enabled: isStringboolTrue( process.env.OUTPUT_TRACE_LOCAL_ON ),
+    name: 'LOCAL',
+    init: localProcessor.init,
+    exec: localProcessor.exec,
+    getDestination: localProcessor.getDestination
+  },
+  {
+    enabled: isStringboolTrue( process.env.OUTPUT_TRACE_REMOTE_ON ),
+    name: 'REMOTE',
+    init: s3Processor.init,
+    exec: s3Processor.exec,
+    getDestination: s3Processor.getDestination
+  }
+];
+
+/**
+ * Returns the destinations for a given execution context
+ *
+ * @param {object} executionContext
+ * @param {string} executionContext.startTime
+ * @param {string} executionContext.workflowId
+ * @param {string} executionContext.workflowName
+ * @param {boolean} executionContext.disableTrace
+ * @returns {object} A trace destinations object: { [dest-name]: 'path' }
+ */
+export const getDestinations = executionContext =>
+  processors.reduce( ( o, p ) =>
+    Object.assign( o, { [p.name.toLowerCase()]: p.enabled && !executionContext.disableTrace ? p.getDestination( executionContext ) : null } )
+  , {} );
+
+/**
+ * Starts processors based on env vars and attach them to the main bus to listen trace events
+ */
+export const init = async () => {
+  for ( const p of processors.filter( p => p.enabled ) ) {
+    await p.init();
+    traceBus.addListener( 'entry', async ( ...args ) => {
+      try {
+        await p.exec( ...args );
+      } catch ( error ) {
+        log.error( 'Processor execution error', { processor: p.name, error: error.message, stack: error.stack } );
+      }
+    } );
+  }
+};
+
+/**
+ * Serialize details of an event
+ */
+const serializeDetails = details => details instanceof Error ? serializeError( details ) : details;
+
+/**
+ * Creates a new trace event phase and sends it to be written
+ *
+ * @param {string} phase - The phase
+ * @param {object} fields - All the trace fields
+ * @returns {void}
+ */
+export const addEventPhase = ( phase, { kind, name, id, parentId, details, executionContext } ) => {
+  // Ignores internal steps in the actual trace files, ignore trace if the flag is true
+  if ( kind !== ComponentType.INTERNAL_STEP && !executionContext.disableTrace ) {
+    traceBus.emit( 'entry', {
+      executionContext,
+      entry: { kind, phase, name, id, parentId, phase, timestamp: Date.now(), details: serializeDetails( details ) }
+    } );
+  }
+};
+
+/**
+ * Adds an Event Phase, complementing the options with parentId and executionContext from the async storage.
+ *
+ * This function will have no effect if called from outside an Temporal Workflow/Activity environment,
+ * so it is safe to be used on unit tests or any dependencies that might be used elsewhere
+ *
+ * @param {object} options - The common trace configurations
+ */
+export function addEventPhaseWithContext( phase, options ) {
+  const storeContent = Storage.load();
+  if ( storeContent ) { // If there is no storageContext this was not called from an Temporal Environment
+    const { parentId, executionContext } = storeContent;
+    addEventPhase( phase, { ...options, parentId, executionContext } );
+  }
+};

package/src/tracing/trace_engine.spec.js

@@ -0,0 +1,199 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const storageLoadMock = vi.fn();
+vi.mock( '#async_storage', () => ( {
+  Storage: { load: storageLoadMock }
+} ) );
+
+const localInitMock = vi.fn( async () => {} );
+const localExecMock = vi.fn();
+const localGetDestinationMock = vi.fn( () => '/local/path.json' );
+vi.mock( './processors/local/index.js', () => ( {
+  init: localInitMock,
+  exec: localExecMock,
+  getDestination: localGetDestinationMock
+} ) );
+
+const s3InitMock = vi.fn( async () => {} );
+const s3ExecMock = vi.fn();
+const s3GetDestinationMock = vi.fn( () => 'https://bucket.s3.amazonaws.com/key.json' );
+vi.mock( './processors/s3/index.js', () => ( {
+  init: s3InitMock,
+  exec: s3ExecMock,
+  getDestination: s3GetDestinationMock
+} ) );
+
+async function loadTraceEngine() {
+  vi.resetModules();
+  return import( './trace_engine.js' );
+}
+
+describe( 'tracing/trace_engine', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    delete process.env.OUTPUT_TRACE_LOCAL_ON;
+    delete process.env.OUTPUT_TRACE_REMOTE_ON;
+    storageLoadMock.mockReset();
+  } );
+
+  it( 'init() starts only enabled processors and attaches listeners', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+    process.env.OUTPUT_TRACE_REMOTE_ON = '0';
+    const { init, addEventPhase } = await loadTraceEngine();
+
+    await init();
+
+    expect( localInitMock ).toHaveBeenCalledTimes( 1 );
+    expect( s3InitMock ).not.toHaveBeenCalled();
+
+    const executionContext = { disableTrace: false };
+    addEventPhase( 'start', {
+      kind: 'step', name: 'N', id: '1', parentId: 'p', details: { ok: true }, executionContext
+    } );
+    expect( localExecMock ).toHaveBeenCalledTimes( 1 );
+    const payload = localExecMock.mock.calls[0][0];
+    expect( payload.entry.name ).toBe( 'N' );
+    expect( payload.entry.kind ).toBe( 'step' );
+    expect( payload.entry.phase ).toBe( 'start' );
+    expect( payload.entry.details ).toEqual( { ok: true } );
+    expect( payload.executionContext ).toBe( executionContext );
+  } );
+
+  it( 'addEventPhase() emits an entry consumed by processors', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = 'on';
+    const { init, addEventPhase } = await loadTraceEngine();
+    await init();
+
+    addEventPhase( 'end', {
+      kind: 'workflow', name: 'W', id: '2', parentId: 'p2', details: 'done',
+      executionContext: { disableTrace: false }
+    } );
+    expect( localExecMock ).toHaveBeenCalledTimes( 1 );
+    const payload = localExecMock.mock.calls[0][0];
+    expect( payload.entry.name ).toBe( 'W' );
+    expect( payload.entry.phase ).toBe( 'end' );
+    expect( payload.entry.details ).toBe( 'done' );
+  } );
+
+  it( 'addEventPhase() does not emit when executionContext.disableTrace is true', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+    const { init, addEventPhase } = await loadTraceEngine();
+    await init();
+
+    addEventPhase( 'start', {
+      kind: 'step', name: 'X', id: '1', parentId: 'p', details: {},
+      executionContext: { disableTrace: true }
+    } );
+    expect( localExecMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'addEventPhase() does not emit when kind is INTERNAL_STEP', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+    const { init, addEventPhase } = await loadTraceEngine();
+    await init();
+
+    addEventPhase( 'start', {
+      kind: 'internal_step', name: 'Internal', id: '1', parentId: 'p', details: {},
+      executionContext: { disableTrace: false }
+    } );
+    expect( localExecMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'addEventPhaseWithContext() uses storage when available', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = 'true';
+    storageLoadMock.mockReturnValue( {
+      parentId: 'ctx-p',
+      executionContext: { runId: 'r1', disableTrace: false }
+    } );
+    const { init, addEventPhaseWithContext } = await loadTraceEngine();
+    await init();
+
+    addEventPhaseWithContext( 'tick', { kind: 'step', name: 'S', id: '3', details: 1 } );
+    expect( localExecMock ).toHaveBeenCalledTimes( 1 );
+    const payload = localExecMock.mock.calls[0][0];
+    expect( payload.executionContext ).toEqual( { runId: 'r1', disableTrace: false } );
+    expect( payload.entry.parentId ).toBe( 'ctx-p' );
+    expect( payload.entry.name ).toBe( 'S' );
+    expect( payload.entry.phase ).toBe( 'tick' );
+  } );
+
+  it( 'addEventPhaseWithContext() does not emit when storage executionContext.disableTrace is true', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+    storageLoadMock.mockReturnValue( {
+      parentId: 'ctx-p',
+      executionContext: { runId: 'r1', disableTrace: true }
+    } );
+    const { init, addEventPhaseWithContext } = await loadTraceEngine();
+    await init();
+
+    addEventPhaseWithContext( 'tick', { kind: 'step', name: 'S', id: '3', details: 1 } );
+    expect( localExecMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'addEventPhaseWithContext() is a no-op when storage is absent', async () => {
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+    storageLoadMock.mockReturnValue( undefined );
+    const { init, addEventPhaseWithContext } = await loadTraceEngine();
+    await init();
+
+    addEventPhaseWithContext( 'noop', { kind: 'step', name: 'X', id: '4', details: null } );
+    expect( localExecMock ).not.toHaveBeenCalled();
+  } );
+
+  describe( 'getDestinations()', () => {
+    const executionContext = { workflowId: 'w1', workflowName: 'WF', startTime: 1, disableTrace: false };
+
+    it( 'returns null for both when traces are off (env vars unset)', async () => {
+      const { getDestinations } = await loadTraceEngine();
+      const result = getDestinations( executionContext );
+      expect( result ).toEqual( { local: null, remote: null } );
+      expect( localGetDestinationMock ).not.toHaveBeenCalled();
+      expect( s3GetDestinationMock ).not.toHaveBeenCalled();
+    } );
+
+    it( 'returns null for both when executionContext.disableTrace is true', async () => {
+      process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+      process.env.OUTPUT_TRACE_REMOTE_ON = '1';
+      const { getDestinations } = await loadTraceEngine();
+      const result = getDestinations( { ...executionContext, disableTrace: true } );
+      expect( result ).toEqual( { local: null, remote: null } );
+      expect( localGetDestinationMock ).not.toHaveBeenCalled();
+      expect( s3GetDestinationMock ).not.toHaveBeenCalled();
+    } );
+
+    it( 'returns both destinations when both traces are on', async () => {
+      process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+      process.env.OUTPUT_TRACE_REMOTE_ON = 'true';
+      const { getDestinations } = await loadTraceEngine();
+      const result = getDestinations( executionContext );
+      expect( result ).toEqual( {
+        local: '/local/path.json',
+        remote: 'https://bucket.s3.amazonaws.com/key.json'
+      } );
+      expect( localGetDestinationMock ).toHaveBeenCalledTimes( 1 );
+      expect( localGetDestinationMock ).toHaveBeenCalledWith( executionContext );
+      expect( s3GetDestinationMock ).toHaveBeenCalledTimes( 1 );
+      expect( s3GetDestinationMock ).toHaveBeenCalledWith( executionContext );
+    } );
+
+    it( 'returns local only when local trace on and remote off', async () => {
+      process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+      process.env.OUTPUT_TRACE_REMOTE_ON = '0';
+      const { getDestinations } = await loadTraceEngine();
+      const result = getDestinations( executionContext );
+      expect( result ).toEqual( { local: '/local/path.json', remote: null } );
+      expect( localGetDestinationMock ).toHaveBeenCalledWith( executionContext );
+      expect( s3GetDestinationMock ).not.toHaveBeenCalled();
+    } );
+
+    it( 'returns remote only when local trace off and remote on', async () => {
+      process.env.OUTPUT_TRACE_LOCAL_ON = '0';
+      process.env.OUTPUT_TRACE_REMOTE_ON = 'true';
+      const { getDestinations } = await loadTraceEngine();
+      const result = getDestinations( executionContext );
+      expect( result ).toEqual( { local: null, remote: 'https://bucket.s3.amazonaws.com/key.json' } );
+      expect( localGetDestinationMock ).not.toHaveBeenCalled();
+      expect( s3GetDestinationMock ).toHaveBeenCalledWith( executionContext );
+    } );
+  } );
+} );

package/src/utils/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * > [!WARNING]
+ * > **Internal use only.** Not part of the public API; may change without notice.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Return the first immediate directory of the file invoking the code that called this function.
+ *
+ * Excludes `@outputai/core`, node, and other internal paths.
+ */
+export function resolveInvocationDir(): string;
+
+/**
+ * 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
+ */
+export function clone( object: object ): object;
+
+/**
+ * Receives an error as argument and throws it.
+ *
+ * @param error
+ * @throws {Error}
+ */
+export function throws( error: Error ): void;
+
+/**
+ * Attach given value to an object with the METADATA_ACCESS_SYMBOL symbol as key.
+ *
+ * @param target
+ * @param value
+ * @returns
+ */
+export function setMetadata( target: object, value: object ): void;
+
+/**
+ * Read metadata previously attached via setMetadata.
+ *
+ * @param target - The function or object to read metadata from.
+ * @returns The metadata object, or null if none is attached.
+ */
+export function getMetadata( target: Function ): { name: string; description?: string; type?: string } | null;
+
+/** Represents a {Response} serialized to plain object  */
+export type SerializedFetchResponse = {
+  /** The response url */
+  url: string,
+
+  /** The response status code */
+  status: number,
+
+  /** The response status text */
+  statusText: string,
+
+  /** Flag indicating if the request succeeded */
+  ok: boolean,
+
+  /** Object with response headers */
+  headers: Record<string, string>,
+
+  /** Response body, either JSON, text or arrayBuffer converter to base64 */
+  body: object | string
+};
+
+/**
+ * Consumes an HTTP `Response` and serializes it to a plain object.
+ *
+ * @param response - The response to serialize.
+ * @returns SerializedFetchResponse
+ */
+export function serializeFetchResponse( response: Response ): SerializedFetchResponse;
+
+export type SerializedBodyAndContentType = {
+  /** The body as a string when possible; otherwise the original value */
+  body: string | unknown,
+  /** The inferred `Content-Type` header value, if any */
+  contentType: string | undefined
+};
+
+/**
+ * Serializes a payload for use as a fetch POST body and infers its `Content-Type`.
+ *
+ * @param body - The payload to serialize.
+ * @returns The serialized body and inferred `Content-Type`.
+ */
+export function serializeBodyAndInferContentType( body: unknown ): SerializedBodyAndContentType;
+
+/**
+ * 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.
+ */
+export function isPlainObject( object: unknown ): boolean;
+
+/**
+ * Returns a copy of an array with its content shuffled.
+ *
+ * @param arr - The array to shuffle
+ * @returns A shuffled array copy
+ */
+export function shuffleArray( arr: unknown[] ): unknown[];
+
+/**
+ * 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.
+ */
+export function deepMerge( a: object, b: object ): object;
+
+/**
+ * Shortens a UUID to a url-safe base64-like string (custom 64-char alphabet).
+ * Temporal-friendly: no Buffer or crypto; safe to use inside workflows.
+ *
+ * @param uuid - Standard UUID (e.g. `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
+ * @returns Short string using A–Z, a–z, 0–9, `_`, `-` (typically 21–22 chars).
+ */
+export function toUrlSafeBase64( uuid: string ): string;

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,34 @@
+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'
+];
+
+/**
+ * Return the directory of the file invoking the code that called this function
+ * Excludes some internal paths and the sdk itself
+ */
+export default ( 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 );
+};