@output.ai/core 0.0.16 → 0.1.1

package/README.md

@@ -23,26 +23,18 @@ Think that workflows is the orchestrator and steps are executors. So the workflo
 ### workflow.js
 
 ```js
-import { workflow } from '@output.ai/workflow';
+import { workflow, z } from '@output.ai/workflow';
 import { guessByName } from './steps.js';
 
 export default workflow( {
   name: 'guessMyProfession',
   description: 'Guess a person profession by its name',
-  inputSchema: {
-    type: 'object',
-    required: [ 'name' ],
-    properties: {
-      name: { type: 'string'}
-    }
-  },
-  outputSchema: {
-    type: 'object',
-    required: [ 'profession' ],
-    properties: {
-      profession: { type: 'string'}
-    }
-  },
+  inputSchema: z.object( {
+    name: z.string()
+  } ),
+  outputSchema: z.object( {
+    profession: z.string()
+  } ),
   fn: async input => {
     const profession = await guessByName( input.name );
     return { profession };
@@ -57,12 +49,8 @@ import { api } from './api.js'
 
 export const guessByName = step( {
   name: 'guessByName',
-  inputSchema: {
-    type: 'string'
-  },
-  outputSchema: {
-    type: 'string'
-  },
+  inputSchema: z.string(),
+  outputSchema: z.string(),
   fn: async name => {
     const res = await api.consumer( name );
     return res.body;
@@ -138,4 +126,10 @@ Necessary env variables to run the worker locally:
 - `TEMPORAL_API_KEY`: The API key to access remote temporal. If using local temporal, leave it blank;
 - `CATALOG_ID`: The name of the local catalog, always set this. Use your email;
 - `API_AUTH_KEY`: The API key to access the Framework API. Local can be blank, remote use the proper API Key;
-- `TRACING_ENABLED`: A "stringbool" value indicating if traces should be generated or not;
+- `TRACE_LOCAL_ON`: A "stringbool" value indicating if traces should be saved locally, needs REDIS_URL;
+- `TRACE_REMOTE_ON`: A "stringbool" value indicating if traces should be saved remotely, needs REDIS_URL and AWS_* secrets;
+- `REDIS_URL`: The redis address to connect. Only necessary when any type of trace is enabled;
+- `TRACE_REMOTE_S3_BUCKET`: The AWS S3 bucket to send the traces. Only necessary when remote trace is enabled;
+- `AWS_REGION`: AWS region to connect to send the traces, must match the bucket region. Only necessary when remote trace is enabled;
+- `AWS_ACCESS_KEY_ID`: AWS key id. Only necessary when remote trace is enabled;
+- `AWS_SECRET_ACCESS_KEY`: AWS secrete. Only necessary when remote trace is enabled;

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@output.ai/core",
-  "version": "0.0.16",
+  "version": "0.1.1",
   "description": "The core module of the output framework",
   "type": "module",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./tracing": {
+      "types": "./src/tracing/index.d.ts",
+      "import": "./src/tracing/index.js"
+    }
+  },
   "files": [
     "./src",
     "./bin"
@@ -17,19 +25,23 @@
     "worker": "node ./src/worker/index.js"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "3.913.0",
     "@babel/generator": "7.28.3",
     "@babel/parser": "7.28.4",
     "@babel/traverse": "7.28.4",
     "@babel/types": "7.28.4",
-    "@temporalio/worker": "1.13.0",
-    "@temporalio/workflow": "1.13.0",
-    "zod": "4.1.9"
+    "@temporalio/worker": "1.13.1",
+    "@temporalio/workflow": "1.13.1",
+    "redis": "5.8.3",
+    "zod": "4.1.12"
   },
   "license": "UNLICENSED",
   "imports": {
     "#consts": "./src/consts.js",
-    "#configs": "./src/configs.js",
     "#errors": "./src/errors.js",
+    "#utils": "./src/utils.js",
+    "#tracing": "./src/tracing/internal_interface.js",
+    "#async_storage": "./src/async_storage.js",
     "#internal_activities": "./src/internal_activities/index.js"
   }
 }

package/src/consts.js

@@ -1,16 +1,7 @@
-export const SEND_WEBHOOK_ACTIVITY_NAME = '__internal#sendWebhookPost';
-export const READ_TRACE_FILE = '__internal#readTraceFile';
+export const ACTIVITY_SEND_WEBHOOK = '__internal#sendWebhook';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
-export const THIS_LIB_NAME = 'core';
-export const TraceEvent = {
-  WORKFLOW_START: 'workflow_start',
-  WORKFLOW_END: 'workflow_end',
-  STEP_START: 'step_start',
-  STEP_END: 'step_end',
-  EVALUATOR_START: 'evaluator_start',
-  EVALUATOR_END: 'evaluator_end'
-};
+export const WORKFLOW_CATALOG = '$catalog';
 export const ComponentType = {
   EVALUATOR: 'evaluator',
   INTERNAL_STEP: 'internal_step',

package/src/interface/evaluator.js

@@ -48,7 +48,8 @@ export class EvaluationResult {
    * @param {string} [args.reasoning] - The reasoning behind the result
    */
   constructor( args ) {
-    if ( !EvaluationResult.#schema.safeParse( args ) ) {
+    const result = EvaluationResult.#schema.safeParse( args );
+    if ( result.error ) {
       throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
     }
     this.value = args.value;
@@ -73,7 +74,8 @@ export class EvaluationStringResult extends EvaluationResult {
    * @param {string} [args.reasoning] - The reasoning behind the result
    */
   constructor( args ) {
-    if ( !EvaluationStringResult.#valueSchema.safeParse( args.value ) ) {
+    const result = EvaluationStringResult.#valueSchema.safeParse( args.value );
+    if ( result.error ) {
       throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
     }
     super( args );
@@ -96,7 +98,8 @@ export class EvaluationBooleanResult extends EvaluationResult {
    * @param {string} [args.reasoning] - The reasoning behind the result
    */
   constructor( args ) {
-    if ( !EvaluationBooleanResult.#valueSchema.safeParse( args.value ) ) {
+    const result = EvaluationBooleanResult.#valueSchema.safeParse( args.value );
+    if ( result.error ) {
       throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
     }
     super( args );
@@ -119,7 +122,8 @@ export class EvaluationNumberResult extends EvaluationResult {
    * @param {string} [args.reasoning] - The reasoning behind the result
    */
   constructor( args ) {
-    if ( !EvaluationNumberResult.#valueSchema.safeParse( args.value ) ) {
+    const result = EvaluationNumberResult.#valueSchema.safeParse( args.value );
+    if ( result.error ) {
       throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
     }
     super( args );

package/src/interface/step.js

@@ -16,6 +16,6 @@ export function step( { name, description, inputSchema, outputSchema, fn } ) {
     return output;
   };
 
-  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.EVALUATOR } );
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.STEP } );
   return wrapper;
 };

package/src/interface/webhook.js

@@ -1,18 +1,30 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { defineSignal, setHandler, proxyActivities, workflowInfo } from '@temporalio/workflow';
-import { SEND_WEBHOOK_ACTIVITY_NAME } from '#consts';
+import { defineSignal, setHandler, proxyActivities, workflowInfo, proxySinks } from '@temporalio/workflow';
+import { ACTIVITY_SEND_WEBHOOK } from '#consts';
+import { FatalError } from '#errors';
 import { validateCreateWebhook } from './validations/static.js';
 
 export async function createWebhook( { url, payload } ) {
   validateCreateWebhook( { url, payload } );
-  const workflowId = workflowInfo();
+  const { workflowId } = workflowInfo();
 
-  await proxyActivities( temporalActivityConfigs )[SEND_WEBHOOK_ACTIVITY_NAME]( { url, workflowId, payload } );
+  await proxyActivities( {
+    startToCloseTimeout: '3m',
+    retry: {
+      initialInterval: '15s',
+      maximumAttempts: 5,
+      nonRetryableErrorTypes: [ FatalError.name ]
+    }
+  } )[ACTIVITY_SEND_WEBHOOK]( { url, workflowId, payload } );
 
+  const sinks = await proxySinks();
   const resumeSignal = defineSignal( 'resume' );
 
+  const traceId = `${workflowId}-${url}-${Date.now()}`;
+  sinks.trace.addEventStart( { id: traceId, name: 'resume', kind: 'webhook' } );
   return new Promise( resolve =>
     setHandler( resumeSignal, responsePayload => {
+      sinks.trace.addEventEnd( { id: traceId, details: responsePayload } );
       resolve( responsePayload );
     } )
   );

package/src/interface/workflow.js

@@ -1,11 +1,10 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, ApplicationFailure, proxySinks } from '@temporalio/workflow';
+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 { READ_TRACE_FILE, TraceEvent } from '#consts';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -23,62 +22,43 @@ export function workflow( { name, description, inputSchema, outputSchema, fn } )
   const workflowPath = getInvocationDir();
 
   const steps = proxyActivities( temporalActivityConfigs );
-  const sinks = proxySinks();
 
   const wrapper = async input => {
-    try {
-      if ( inWorkflowContext() ) {
-        sinks.log.trace( { event: TraceEvent.WORKFLOW_START, input } );
-      }
-
-      validateWithSchema( inputSchema, input, `Workflow ${name} input` );
-
-      // this returns a plain function, for example, in unit tests
-      if ( !inWorkflowContext() ) {
-        const output = await fn( input );
-        validateWithSchema( outputSchema, output, `Workflow ${name} output` );
-        return output;
-      }
-
-      const { memo, workflowId } = workflowInfo();
-
-      Object.assign( workflowInfo().memo, { workflowPath } );
-
-      // 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 ),
+    validateWithSchema( inputSchema, input, `Workflow ${name} input` );
 
-        startWorkflow: async ( childName, input ) => {
+    // this returns a plain function, for example, in unit tests
+    if ( !inWorkflowContext() ) {
+      const output = await fn( input );
+      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+      return output;
+    }
 
-          // Checks if current memo has rootWorkflowId, which means current execution is already a child
-          // Then it sets the memory for the child execution passing along who's the original workflow is and its type
-          const workflowMemory = memo.rootWorkflowId ?
-            { parentWorkflowId: workflowId, rootWorkflowType: memo.rootWorkflowType, rootWorkflowId: memo.rootWorkflowId } :
-            { parentWorkflowId: workflowId, rootWorkflowId: workflowId, rootWorkflowType: name };
+    const { workflowId, memo, startTime } = workflowInfo();
 
-          return executeChild( childName, { args: input ? [ input ] : [], memo: workflowMemory } );
-        }
-      }, input );
+    // Create the execution context object or preserve if it already exists:
+    // It will always contains the information about the root workflow
+    // It will be used to as context for tracing (connecting events)
+    const executionContext = memo.executionContext ?? {
+      workflowId,
+      workflowName: name,
+      startTime: startTime.getTime()
+    };
 
-      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+    Object.assign( memo, { executionContext } );
 
-      sinks.log.trace( { event: TraceEvent.WORKFLOW_END, output } );
+    // 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 ),
 
-      // add trace if not child
-      if ( !memo.rootWorkflowId ) {
-        const trace = await steps[READ_TRACE_FILE]( { workflowType: name, workflowId } );
-        return { output, trace };
+      startWorkflow: async ( childName, input ) => {
+        return executeChild( childName, { args: input ? [ input ] : [], memo: { executionContext, parentId: workflowId } } );
       }
+    }, input );
 
-      return output;
-    } catch ( error ) {
-      /*
-       * Any errors in the workflow will interrupt its execution since the workflow is designed to orchestrate and
-       * IOs should be made in steps
-       */
-      throw new ApplicationFailure( error.message, error.constructor.name );
-    }
+    validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+
+    return output;
   };
 
   setMetadata( wrapper, { name, description, inputSchema, outputSchema } );

package/src/internal_activities/index.js

@@ -1,11 +1,7 @@
 import { FatalError } from '#errors';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
 import { setMetadata } from '../interface/metadata.js';
 import { ComponentType } from '#consts';
 
-const callerDir = process.argv[2];
-
 /**
  * Send a post to a given URL
  *
@@ -15,7 +11,7 @@ const callerDir = process.argv[2];
  * @param {any} options.payload - The payload to send url
  * @throws {FatalError}
  */
-export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
+export const sendWebhook = async ( { url, workflowId, payload } ) => {
   const request = fetch( url, {
     method: 'POST',
     headers: {
@@ -33,41 +29,11 @@ export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
     }
   } )();
 
-  console.log( '[Core.SendWebhookPost]', res.status, res.statusText );
+  console.log( '[Core.SendWebhook]', res.status, res.statusText );
 
   if ( !res.ok ) {
     throw new FatalError( `Webhook fail: ${res.status}` );
   }
 };
 
-setMetadata( sendWebhookPost, { type: ComponentType.INTERNAL_STEP } );
-
-/**
- * Read the trace file of a given execution and returns the content
- *
- * @param {object} options
- * @param {string} options.workflowType - The type of the workflow
- * @param {string} options.workflowId - The workflow execution id
- * @returns {string[]} Each line of the trace file
- */
-export const readTraceFile = async ( { workflowType, workflowId } ) => {
-  const dir = join( callerDir, 'logs', 'runs', workflowType );
-
-  if ( !existsSync( dir ) ) {
-    console.log( '[Core.ReadTraceFile]', 'Trace folder not found', dir );
-    return [];
-  }
-
-  const suffix = `-${workflowId}.raw`;
-  const matchingFile = readdirSync( dir ).find( f => f.endsWith( suffix ) );
-
-  if ( !matchingFile ) {
-    console.log( '[Core.ReadTraceFile]', 'Trace file not found', dir, suffix );
-    return [];
-  }
-
-  const file = join( dir, matchingFile );
-  return existsSync( file ) ? readFileSync( file, 'utf-8' ).split( '\n' ) : [];
-};
-
-setMetadata( readTraceFile, { type: ComponentType.INTERNAL_STEP, skipTrace: true } );
+setMetadata( sendWebhook, { type: ComponentType.INTERNAL_STEP } );

package/src/tracing/index.d.ts

@@ -0,0 +1,47 @@
+/*
+╭───────────╮
+│ T R A C E │╮
+╰───────────╯│
+ ╰───────────╯
+*/
+
+/**
+ * The public namespace for tracing
+ *
+ * @namespace
+ */
+export declare const Tracing: {
+
+  /**
+   * Adds the start phase of a new event at the default trace for the current workflow.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+   * @param {string} name - The human friendly name of the Event: query, request, create.
+   * @param {any} details - All details attached to this Event Phase. DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventStart( args: { id: string; kind: string; name: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Adds the end phase at an event at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventEnd( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Adds the error phase at an event as error at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventError( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+};

package/src/tracing/index.js

@@ -0,0 +1,45 @@
+import { addEventPhaseWithContext } from './trace_engine.js';
+
+/**
+ * The public namespace for tracing
+ *
+ * @namespace
+ */
+export const Tracing = {
+
+  /**
+   * Adds the start phase of a new event at the default trace for the current workflow.
+   *
+   * @param {object} args
+   * @param {string} args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {string} args.kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+   * @param {string} args.name - The human friendly name of the Event: query, request, create.
+   * @param {object} args.details - All details attached to this Event Phase. DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventStart: ( { id, kind, name, details } ) => addEventPhaseWithContext( 'start', { kind, name, details, id } ),
+
+  /**
+   * Adds the end phase at an event at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {object} args
+   * @param {string} args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {object} args.details - All details attached to this Event Phase. DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventEnd: ( { id, details } ) => addEventPhaseWithContext( 'end', { id, details } ),
+
+  /**
+   * Adds the error phase at an event as error at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {object} args
+   * @param {string} args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {object} args.details - All details attached to this Event Phase. DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventError: ( { id, details } ) => addEventPhaseWithContext( 'error', { id, details } )
+};

package/src/tracing/internal_interface.js

@@ -0,0 +1,66 @@
+import { addEventPhase, init } from './trace_engine.js';
+
+/**
+ * Init method, if not called, no processors are attached and trace functions are dummy
+ */
+export { init };
+
+/**
+ * Trace nomenclature
+ *
+ * Trace - The collection of Events;
+ * Event - Any entry in the Trace file, must have the two phases START and END or ERROR;
+ * Phase - An specific part of an Event, either START or the conclusive END or ERROR;
+ */
+
+/**
+ * Internal use only
+ *
+ * Adds the start phase of a new event at the default trace for the current workflow.
+ *
+ * @param {object} args
+ * @param {string} args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} args.kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} args.name - The human friendly name of the Event: query, request, create.
+ * @param {any} args.details - All details attached to this Event Phase. DB queried records, HTTP response body.
+ * @param {string} args.parentId - The parent Event, used to build a three.
+ * @param {object} args.executionContext - The original execution context from the workflow
+ * @returns {void}
+ */
+export const addEventStart = options => addEventPhase( 'start', options );
+
+/**
+ * Internal use only
+ *
+ * Adds the end phase at an event at the default trace for the current workflow.
+ *
+ * It needs to use the same id of the start phase.
+ *
+ * @param {object} args
+ * @param {string} args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} args.kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} args.name - The human friendly name of the Event: query, request, create.
+ * @param {any} args.details - All details attached to this Event Phase. DB queried records, HTTP response body.
+ * @param {string} args.parentId - The parent Event, used to build a three.
+ * @param {object} args.executionContext - The original execution context from the workflow
+ * @returns {void}
+ */
+export const addEventEnd = options => addEventPhase( 'end', options );
+
+/**
+ * Internal use only
+ *
+ * Adds the error phase at an event as error at the default trace for the current workflow.
+ *
+ * It needs to use the same id of the start phase.
+ *
+ * @param {object} args
+ * @param {string} args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} args.kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} args.name - The human friendly name of the Event: query, request, create.
+ * @param {any} args.details - All details attached to this Event Phase. DB queried records, HTTP response body.
+ * @param {string} args.parentId - The parent Event, used to build a three.
+ * @param {object} args.executionContext - The original execution context from the workflow
+ * @returns {void}
+ */
+export const addEventError = options => addEventPhase( 'error', options );

package/src/tracing/processors/local/index.js

@@ -0,0 +1,50 @@
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'url';
+import buildTraceTree from '../../tools/build_trace_tree.js';
+import { EOL } from 'node:os';
+
+const oneWeekInMS = 1000 * 60 * 60 * 24 * 7;
+const __dirname = dirname( fileURLToPath( import.meta.url ) );
+const tempDir = join( __dirname, 'temp', 'traces' );
+
+const accumulate = ( { entry, executionContext: { workflowId, startTime } } ) => {
+  const path = join( tempDir, `${startTime}_${workflowId}.trace` );
+  appendFileSync( path, JSON.stringify( entry ) + EOL, 'utf-8' );
+  return readFileSync( path, 'utf-8' ).split( EOL ).slice( 0, -1 ).map( v => JSON.parse( v ) );
+};
+
+const cleanupOldTempFiles = ( threshold = Date.now() - oneWeekInMS ) =>
+  readdirSync( tempDir )
+    .filter( f => +f.split( '_' )[0] < threshold )
+    .forEach( f => rmSync( join( tempDir, f ) ) );
+
+/**
+ * Init this processor
+ */
+export const init = () => {
+  mkdirSync( tempDir, { recursive: true } );
+  cleanupOldTempFiles();
+};
+
+/**
+ * Execute this processor:
+ *
+ * Persist a trace tree file to local file system, updating upon each new entry
+ *
+ * @param {object} args
+ * @param {object} entry - Trace event phase
+ * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ * @returns
+ */
+export const exec = ( { entry, executionContext } ) => {
+  const { workflowId, workflowName, startTime } = executionContext;
+  const content = buildTraceTree( accumulate( { entry, executionContext } ) );
+
+  const timestamp = new Date( startTime ).toISOString().replace( /[:T.]/g, '-' );
+  const dir = join( process.argv[2], 'logs', 'runs', workflowName );
+  const path = join( dir, `${timestamp}_${workflowId}.json` );
+
+  mkdirSync( dir, { recursive: true } );
+  writeFileSync( path, JSON.stringify( content, undefined, 2 ) + EOL, 'utf-8' );
+};

package/src/tracing/processors/local/index.spec.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// In-memory fs mock store
+const store = { files: new Map() };
+const mkdirSyncMock = vi.fn();
+const writeFileSyncMock = vi.fn();
+const appendFileSyncMock = vi.fn( ( path, data ) => {
+  const prev = store.files.get( path ) ?? '';
+  store.files.set( path, prev + data );
+} );
+const readFileSyncMock = vi.fn( path => store.files.get( path ) ?? '' );
+const readdirSyncMock = vi.fn( () => [] );
+const rmSyncMock = vi.fn();
+
+vi.mock( 'node:fs', () => ( {
+  mkdirSync: mkdirSyncMock,
+  writeFileSync: writeFileSyncMock,
+  appendFileSync: appendFileSyncMock,
+  readFileSync: readFileSyncMock,
+  readdirSync: readdirSyncMock,
+  rmSync: rmSyncMock
+} ) );
+
+const buildTraceTreeMock = vi.fn( entries => ( { count: entries.length } ) );
+vi.mock( '../../tools/build_trace_tree.js', () => ( { default: buildTraceTreeMock } ) );
+
+describe( 'tracing/processors/local', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    store.files.clear();
+    process.argv[2] = '/tmp/project';
+  } );
+
+  it( 'init(): creates temp dir and cleans up old files', async () => {
+    const { init } = await import( './index.js' );
+
+    const now = Date.now();
+    readdirSyncMock.mockReturnValue( [ `${now - ( 8 * 24 * 60 * 60 * 1000 )}_old.trace`, `${now}_new.trace` ] );
+
+    init();
+
+    expect( mkdirSyncMock ).toHaveBeenCalledWith( expect.stringMatching( /temp\/traces$/ ), { recursive: true } );
+    expect( rmSyncMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'exec(): accumulates entries and writes aggregated tree', async () => {
+    const { exec, init } = await import( './index.js' );
+    init();
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+
+    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
+    exec( { ...ctx, entry: { name: 'A', phase: 'tick', timestamp: startTime + 1 } } );
+    exec( { ...ctx, entry: { name: 'A', phase: 'end', timestamp: startTime + 2 } } );
+
+    // buildTraceTree called with 1, 2, 3 entries respectively
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 3 );
+    expect( buildTraceTreeMock.mock.calls.at( -1 )[0].length ).toBe( 3 );
+
+    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 3 );
+    const [ writtenPath, content ] = writeFileSyncMock.mock.calls.at( -1 );
+    expect( writtenPath ).toMatch( /\/logs\/runs\/WF\// );
+    expect( JSON.parse( content.trim() ).count ).toBe( 3 );
+  } );
+} );
+