@output.ai/core 0.1.0 → 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,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -25,20 +25,22 @@
     "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",
-    "#tracing": "./src/tracing/index.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,7 +1,7 @@
 export const ACTIVITY_SEND_WEBHOOK = '__internal#sendWebhook';
-export const ACTIVITY_READ_TRACE_FILE = '__internal#readTraceFile';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
+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/workflow.js

@@ -5,7 +5,6 @@ import { setMetadata } from './metadata.js';
 import { FatalError, ValidationError } from '#errors';
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
-import { ACTIVITY_READ_TRACE_FILE } from '#consts';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -34,13 +33,18 @@ export function workflow( { name, description, inputSchema, outputSchema, fn } )
       return output;
     }
 
-    const { workflowId, memo } = workflowInfo();
+    const { workflowId, memo, startTime } = workflowInfo();
 
-    // keep trace id and helm from memo if present (child workflow)
-    const traceId = memo.traceId ?? workflowId;
-    const traceHelm = memo.traceHelm ?? name;
+    // 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()
+    };
 
-    Object.assign( memo, { traceId, traceHelm } );
+    Object.assign( memo, { executionContext } );
 
     // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
     const output = await fn.call( {
@@ -48,19 +52,12 @@ export function workflow( { name, description, inputSchema, outputSchema, fn } )
       invokeEvaluator: async ( evaluatorName, input ) => steps[`${workflowPath}#${evaluatorName}`]( input ),
 
       startWorkflow: async ( childName, input ) => {
-        return executeChild( childName, { args: input ? [ input ] : [], memo: { traceId, traceHelm, parentId: workflowId } } );
+        return executeChild( childName, { args: input ? [ input ] : [], memo: { executionContext, parentId: workflowId } } );
       }
     }, input );
 
     validateWithSchema( outputSchema, output, `Workflow ${name} output` );
 
-    // Adds trace file content to the output if it is the root workflow
-    // @TODO this will be replaced in favor of a persistent storage elsewhere
-    if ( !memo.parentId ) {
-      const trace = await steps[ACTIVITY_READ_TRACE_FILE]( { traceId, traceHelm } );
-      return { output, trace };
-    }
-
     return output;
   };
 

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
  *
@@ -41,31 +37,3 @@ export const sendWebhook = async ( { url, workflowId, payload } ) => {
 };
 
 setMetadata( sendWebhook, { type: ComponentType.INTERNAL_STEP } );
-
-/**
- * Read the trace file of a given execution and returns the content
- *
- * @param {object} options
- * @param {string} options.traceId - The is of the trace
- * @param {string} options.traceHelm - The helm of the trace file
- * @returns {string[]} Each line of the trace file
- */
-export const readTraceFile = async ( { traceId, traceHelm } ) => {
-  const dir = join( callerDir, 'logs', 'runs', traceHelm );
-
-  if ( !existsSync( dir ) ) {
-    console.log( '[Core.ReadTraceFile]', 'Trace folder not found', dir );
-    return [];
-  }
-
-  const fileName = readdirSync( dir ).find( f => f.endsWith( `-${traceId}.raw` ) );
-
-  if ( !fileName ) {
-    console.log( '[Core.ReadTraceFile]', 'Trace file not found', { traceId, traceHelm } );
-    return [];
-  }
-
-  return readFileSync( join( dir, fileName ), 'utf-8' ).split( '\n' );
-};
-
-setMetadata( readTraceFile, { type: ComponentType.INTERNAL_STEP, skipTrace: true } );

package/src/tracing/index.d.ts

@@ -17,8 +17,8 @@ export declare const Tracing: {
    *
    * @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: eg: query, request, create.
-   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @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
@@ -29,7 +29,7 @@ export declare const Tracing: {
    * 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. Eg: DB queried records, HTTP response body.
+   * @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
@@ -40,7 +40,7 @@ export declare const Tracing: {
    * 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. Eg: DB queried records, HTTP response body.
+   * @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

@@ -1,116 +1,4 @@
-import { Storage } from '#async_storage';
-import { mkdirSync, existsSync, readdirSync, appendFileSync } from 'node:fs';
-import { join } from 'path';
-import { EOL } from 'os';
-import { buildLogTree } from './tracer_tree.js';
-import { serializeError } from './utils.js';
-
-const callerDir = process.argv[2];
-// It is is isolated here instead of #configs to allow this module to be exported without all other configs requirements
-const tracingEnabled = [ '1', 'true', 'on' ].includes( process.env.TRACING_ENABLED );
-
-/**
- * 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;
- */
-
-/**
- * Adds the Trace Event Phase to the trace file
- *
- * @param {string} phase - The phase
- * @param {object} options - All the trace fields
- * @returns {void}
- */
-function addEventPhase( phase, { kind, details, id, name, parentId, traceId, traceHelm } ) {
-  if ( !tracingEnabled || name === 'catalog' ) {
-    return;
-  }
-
-  const parsedDetails = details instanceof Error ? serializeError( details ) : details;
-  const timestamp = Date.now();
-  const entry = { phase, kind, details: parsedDetails, id, name, timestamp, parentId };
-  const outputDir = join( callerDir, 'logs', 'runs', traceHelm );
-
-  if ( !existsSync( outputDir ) ) {
-    mkdirSync( outputDir, { recursive: true } );
-  }
-
-  const suffix = `-${traceId}.raw`;
-  const logFile = readdirSync( outputDir ).find( f => f.endsWith( suffix ) ) ?? `${new Date( timestamp ).toISOString()}-${suffix}`;
-  const logPath = join( outputDir, logFile );
-
-  appendFileSync( logPath, JSON.stringify( entry ) + EOL, 'utf-8' );
-  buildLogTree( logPath );
-};
-
-/**
- * Internal use only
- *
- * 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: eg: query, request, create.
- * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
- * @param {string} parentId - The parent Event, used to build a three.
- * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
- * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
- * @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 {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: eg: query, request, create.
- * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
- * @param {string} parentId - The parent Event, used to build a three.
- * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
- * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
- * @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 {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: eg: query, request, create.
- * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
- * @param {string} parentId - The parent Event, used to build a three.
- * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
- * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
- * @returns {void}
- */
-export const addEventError = options => addEventPhase( 'error', options );
-
-/**
- * Adds an Event Phase reading traceId, traceHelm and parentId from the context.
- *
- * @param {object} options - The common trace configurations
- */
-function addEventPhaseWithContext( phase, options ) {
-  const storeContent = Storage.load();
-  if ( !storeContent ) { // means this was called from a unit test
-    return;
-  }
-  const { parentId, traceId, traceHelm } = storeContent;
-  addEventPhase( phase, { ...options, parentId, traceId, traceHelm } );
-};
+import { addEventPhaseWithContext } from './trace_engine.js';
 
 /**
  * The public namespace for tracing
@@ -122,10 +10,11 @@ export 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: eg: query, request, create.
-   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @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 } ),
@@ -135,8 +24,9 @@ export const Tracing = {
    *
    * 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. Eg: DB queried records, HTTP response body.
+   * @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 } ),
@@ -146,8 +36,9 @@ export const Tracing = {
    *
    * 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. Eg: DB queried records, HTTP response body.
+   * @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 );
+  } );
+} );
+

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

@@ -0,0 +1,51 @@
+import { upload } from './s3_client.js';
+import { getRedisClient } from './redis_client.js';
+import buildTraceTree from '../../tools/build_trace_tree.js';
+import { EOL } from 'node:os';
+
+const oneMonthInSeconds = 60 * 60 * 24 * 30;
+
+const accumulate = async ( { entry, executionContext: { workflowName, workflowId } } ) => {
+  const key = `traces/${workflowName}/${workflowId}`;
+  const transaction = ( await getRedisClient() ).multi();
+
+  transaction.zAdd( key, [
+    { score: entry.timestamp, value: JSON.stringify( entry ) }
+  ], { NX: true } );
+  transaction.expire( key, oneMonthInSeconds, 'GT' );
+  transaction.zRange( key, 0, -1 );
+  const [ ,, zList ] = await transaction.exec();
+  return zList.map( v => JSON.parse( v ) );
+};
+
+const getS3Key = ( { startTime, workflowId, workflowName } ) => {
+  const isoDate = new Date( startTime ).toISOString();
+  const [ year, month, day ] = isoDate.split( /\D/, 3 );
+  const timeStamp = isoDate.replace( /[:T.]/g, '-' );
+  return `${workflowName}/${year}/${month}/${day}/${timeStamp}_${workflowId}.json`;
+};
+
+/**
+ * Init this processor
+ */
+export const init = async () => {
+  await getRedisClient();
+};
+
+/**
+ * Execute this processor: send a complete trace tree file to S3 when the workflow finishes
+ *
+ * @param {object} args
+ * @param {object} entry - Trace event phase
+ * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ */
+export const exec = async ( { entry, executionContext } ) => {
+  const { workflowName, workflowId, startTime } = executionContext;
+  const content = buildTraceTree( await accumulate( { entry, executionContext } ) );
+
+  const isRootWorkflowEnd = !entry.parentId && entry.phase !== 'start';
+  return isRootWorkflowEnd ? upload( {
+    key: getS3Key( { workflowId, workflowName, startTime } ),
+    content: JSON.stringify( content, undefined, 2 ) + EOL
+  } ) : 0;
+};