@outputai/core 0.2.1-next.7e1c76d.0 → 0.2.1-next.815b3a9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.2.1-next.7e1c76d.0",
+  "version": "0.2.1-next.815b3a9.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/activity_integration/tracing.d.ts

@@ -1,32 +1,45 @@
 /**
- * Record the start of an event on the default trace for the current workflow.
+ * Creates a new event.
  *
- * @param args - Event information
- * @param args.id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param args
+ * @param args.id - A unique id for the Event.
  * @param args.kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
- * @param args.name - The human friendly name of the Event: query, request, create.
- * @param args.details - Arbitrary metadata associated with this phase (e.g., payloads, summaries).
+ * @param args.name - The human-friendly name of the Event: query, request, create.
+ * @param args.details - Arbitrary data to add to this event, it will be used as the "input" field.
  */
 export declare function addEventStart( args: { id: string; kind: string; name: string; details: unknown } ): void;
 
 /**
- * Record the end of an event on the default trace for the current workflow.
+ * Concludes an event.
  *
- * Use the same id as the start phase to correlate phases.
- *
- * @param args - Event information
- * @param args.id - Identifier matching the event's start phase.
- * @param args.details - Arbitrary metadata associated with this phase (e.g., results, response body).
+ * @param args
+ * @param args.id - The id of the event to conclude.
+ * @param args.details - Arbitrary data to add to this event, it will be used as the "output" field.
  */
 export declare function addEventEnd( args: { id: string; details: unknown } ): void;
 
 /**
- * Record an error for an event on the default trace for the current workflow.
- *
- * Use the same id as the start phase to correlate phases.
+ * Concludes an event with an error.
  *
- * @param args - Event metadata for the error phase.
- * @param args.id - Identifier matching the event's start phase.
- * @param args.details - Arbitrary metadata associated with this phase, possible error info.
+ * @param args
+ * @param args.id - The id of the event to conclude.
+ * @param args.details - Arbitrary data to add to this event, it will be used as the "error" field.
  */
 export declare function addEventError( args: { id: string; details: unknown } ): void;
+
+/**
+ * Adds an attribute to an event.
+ *
+ * @param args
+ * @param args.eventId - The id of the event to attach the attribute to.
+ * @param args.name - The attribute name
+ * @param args.value - The attribute value
+ */
+export declare function addEventAttribute( args: { eventId: string; name: string, value: unknown } ): void;
+
+/**
+ * Known attributes.
+ */
+export declare const Attribute: {
+  COST: 'cost';
+};

package/src/activity_integration/tracing.js

@@ -1,37 +1,53 @@
-import { addEventPhaseWithContext } from '#tracing';
+import { addEventActionWithContext, EventAction } from '#tracing';
 
 /**
- * Adds the start phase of a new event at the default trace for the current workflow.
+ * Creates a new event.
  *
  * @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.id - A unique id for the Event.
  * @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.
+ * @param {string} args.name - The human-friendly name of the Event: query, request, create.
+ * @param {object} args.details - Arbitrary data to add to this event, it will be used as the "input" field.
  * @returns {void}
  */
-export const addEventStart = ( { id, kind, name, details } ) => addEventPhaseWithContext( 'start', { kind, name, details, id } );
+export const addEventStart = ( { id, kind, name, details } ) =>
+  addEventActionWithContext( EventAction.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.
+ * Concludes an event.
  *
  * @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.
+ * @param {string} args.id - The id of the event to conclude.
+ * @param {object} args.details - Arbitrary data to add to this event, it will be used as the "output" field.
  * @returns {void}
  */
-export const addEventEnd = ( { id, details } ) => addEventPhaseWithContext( 'end', { id, details } );
+export const addEventEnd = ( { id, details } ) => addEventActionWithContext( EventAction.END, { id, details } );
 
 /**
- * Adds the error phase at an event as error at the default trace for the current workflow.
+ * Concludes an event with an error.
  *
- * It needs to use the same id of the start phase.
+ * @param {object} args
+ * @param {string} args.id - The id of the event to conclude.
+ * @param {object} args.details - Arbitrary data to add to this event, it will be used as the "error" field.
+ * @returns {void}
+ */
+export const addEventError = ( { id, details } ) => addEventActionWithContext( EventAction.ERROR, { id, details } );
+
+/**
+ * Adds an attribute to an event.
  *
  * @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.
+ * @param {string} args.eventId - The id of the event to attach the attribute to.
+ * @param {string} args.name - The attribute name
+ * @param {unknown} args.value - The attribute value
  * @returns {void}
  */
-export const addEventError = ( { id, details } ) => addEventPhaseWithContext( 'error', { id, details } );
+export const addEventAttribute = ( { eventId, name, value } ) =>
+  addEventActionWithContext( EventAction.ADD_ATTR, { id: eventId, details: { name, value } } );
+
+/**
+ * Known attributes
+ */
+export const Attribute = {
+  COST: 'cost'
+};

package/src/tracing/internal_interface.js

@@ -1,4 +1,5 @@
-import { addEventPhase, addEventPhaseWithContext, init, getDestinations } from './trace_engine.js';
+import { addEventAction, addEventActionWithContext, init, getDestinations } from './trace_engine.js';
+import { EventAction } from './trace_consts.js';
 
 /**
  * Init method, if not called, no processors are attached and trace functions are dummy
@@ -6,66 +7,71 @@ import { addEventPhase, addEventPhaseWithContext, init, getDestinations } from '
 export { init, getDestinations };
 
 /**
- * Internal use only - adds event phase with AsyncLocalStorage context resolution
+ * Internal use only - adds an action with AsyncLocalStorage context resolution
  */
-export { addEventPhaseWithContext };
+export { addEventActionWithContext };
+
+export { EventAction };
 
 /**
  * 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;
+ * Event - Any entry in the Trace file must have both START and END/ERROR actions, plus any number of ADD_ATTR actions;
+ * Action - A specific part of an Event: START, END, ERROR, or ADD_ATTR;
  */
 
 /**
  * Internal use only
  *
- * Adds the start phase of a new event at the default trace for the current workflow.
+ * Creates a new event and appends it to the trace.
  *
  * @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.id - A unique id for the Event.
  * @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 {string} args.name - The human-friendly name of the Event: query, request, create.
+ * @param {any} args.details - Arbitrary data to add to this event, it will be used as the "input" field.
+ * @param {string} args.parentId - The parent Event, used to build a tree.
  * @param {object} args.executionContext - The original execution context from the workflow
  * @returns {void}
  */
-export const addEventStart = options => addEventPhase( 'start', options );
+export const addEventStart = options => addEventAction( EventAction.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.
+ * Concludes an event, matching by its id.
  *
  * @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 {string} args.id - The id of the event to conclude.
+ * @param {any} args.details - Arbitrary data to add to the event; it is used as the "output" field.
  * @param {object} args.executionContext - The original execution context from the workflow
  * @returns {void}
  */
-export const addEventEnd = options => addEventPhase( 'end', options );
+export const addEventEnd = options => addEventAction( EventAction.END, options );
 
 /**
  * Internal use only
  *
- * Adds the error phase at an event as error at the default trace for the current workflow.
+ * Concludes an event with an error, matching by its id.
+ *
+ * @param {object} args
+ * @param {string} args.id - The id of the event to conclude.
+ * @param {any} args.details - Arbitrary data to add to the event; it is used as the "error" field.
+ * @param {object} args.executionContext - The original execution context from the workflow
+ * @returns {void}
+ */
+export const addEventError = options => addEventAction( EventAction.ERROR, options );
+
+/**
+ * Internal use only
  *
- * It needs to use the same id of the start phase.
+ * Adds an attribute to an event using its id.
  *
  * @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 {string} args.id - The id of the event to attach the attribute to.
+ * @param {object} args.details - The attribute to add to this event, must be in `{ name: string, value: any }` format.
  * @param {object} args.executionContext - The original execution context from the workflow
  * @returns {void}
  */
-export const addEventError = options => addEventPhase( 'error', options );
+export const addEventAttribute = options => addEventAction( EventAction.ADD_ATTR, options );

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

@@ -23,7 +23,7 @@ const tempTraceFilesDir = join( __dirname, 'temp', 'traces' );
 const createTempFilePath = ( { workflowId, startTime } ) => join( tempTraceFilesDir, `${startTime}_${workflowId}.trace` );
 
 /**
- * Adds an trace entry to the accumulation file
+ * Adds a trace entry to the accumulation file.
  * @param {object} entry - The trace entry
  * @param {string} path - Accumulation file path
  */
@@ -100,12 +100,13 @@ export const init = () => {
 /**
  * Execute this processor:
  *
- * Append each trace entry to a temp file; when the root workflow ends (non-start phase on the
- * workflow id) or any entry is an error phase, build the trace tree and write the JSON file once.
+ * Appends each trace entry to a temp file.
+ *
+ * When the root workflow ends or the entry is an error action, build the trace tree and write the JSON file.
  *
  * @param {object} args
- * @param {object} entry - Trace event phase
- * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ * @param {object} args.entry - The trace entry to append.
+ * @param {object} args.executionContext - Execution info: workflowId, workflowName, startTime
  * @returns {void}
  */
 export const exec = ( { entry, executionContext } ) => {
@@ -113,8 +114,8 @@ export const exec = ( { entry, executionContext } ) => {
   const tempFilePath = createTempFilePath( executionContext );
   addEntry( entry, tempFilePath );
 
-  const isRootWorkflowEnd = entry.id === workflowId && entry.phase !== 'start';
-  const isError = entry.phase === 'error';
+  const isRootWorkflowEnd = entry.id === workflowId && entry.action !== 'start';
+  const isError = entry.action === 'error';
 
   if ( !isRootWorkflowEnd && !isError ) {
     return;

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

@@ -25,10 +25,10 @@ vi.mock( 'node:fs', () => ( {
 const buildTraceTreeMock = vi.fn( entries => ( { count: entries.length } ) );
 vi.mock( '../../tools/build_trace_tree.js', () => ( { default: buildTraceTreeMock } ) );
 
-/** Flush happens when root id matches workflowId and phase is not start, or when phase is error. */
-const rootStart = ( workflowId, ts ) => ( { id: workflowId, phase: 'start', timestamp: ts } );
-const rootEnd = ( workflowId, ts ) => ( { id: workflowId, phase: 'end', timestamp: ts } );
-const childTick = ( id, ts ) => ( { id, phase: 'tick', timestamp: ts } );
+/** Flush happens when the root id matches workflowId and action is not 'start', or when action is 'error'. */
+const rootStart = ( workflowId, ts ) => ( { id: workflowId, action: 'start', timestamp: ts } );
+const rootEnd = ( workflowId, ts ) => ( { id: workflowId, action: 'end', timestamp: ts } );
+const childTick = ( id, ts ) => ( { id, action: 'tick', timestamp: ts } );
 
 describe( 'tracing/processors/local', () => {
   beforeEach( () => {
@@ -86,7 +86,7 @@ describe( 'tracing/processors/local', () => {
     expect( writeFileSyncMock ).not.toHaveBeenCalled();
   } );
 
-  it( 'exec(): flushes on error phase before root end', async () => {
+  it( 'exec(): flushes on error action before root end', async () => {
     const { exec, init } = await import( './index.js' );
     init();
 
@@ -95,7 +95,7 @@ describe( 'tracing/processors/local', () => {
     const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
 
     exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
-    exec( { ...ctx, entry: { id: 'step-1', phase: 'error', timestamp: startTime + 1 } } );
+    exec( { ...ctx, entry: { id: 'step-1', action: 'error', timestamp: startTime + 1 } } );
 
     expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 1 );
     expect( buildTraceTreeMock.mock.calls[0][0] ).toHaveLength( 2 );

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

@@ -67,11 +67,15 @@ export const init = async () => {
 };
 
 /**
- * Execute this processor: send a complete trace tree file to S3 when the workflow finishes
+ * Execute this processor:
+ *
+ * Appends each trace entry to Redis.
+ *
+ * When the root workflow ends or the entry is an error action, it builds the trace tree and uploads it to S3.
  *
  * @param {object} args
- * @param {object} entry - Trace event phase
- * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ * @param {object} args.entry - The trace entry to append
+ * @param {object} args.executionContext - Execution info: workflowId, workflowName, startTime
  */
 export const exec = async ( { entry, executionContext } ) => {
   const { workflowName, workflowId, startTime } = executionContext;
@@ -79,7 +83,7 @@ export const exec = async ( { entry, executionContext } ) => {
 
   await addEntry( entry, cacheKey );
 
-  const isRootWorkflowEnd = entry.id === workflowId && entry.phase !== 'start';
+  const isRootWorkflowEnd = entry.id === workflowId && entry.action !== 'start';
   if ( !isRootWorkflowEnd ) {
     return;
   }

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

@@ -52,9 +52,9 @@ describe( 'tracing/processors/s3', () => {
 
     redisMulti.exec.mockResolvedValue( [] );
 
-    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', phase: 'start', details: {}, timestamp: startTime };
-    const activityStart = { id: 'act-1', name: 'DoSomething', kind: 'step', parentId: 'id1', phase: 'start', details: {}, timestamp: startTime + 1 };
-    const workflowEnd = { id: 'id1', phase: 'end', details: { ok: true }, timestamp: startTime + 2 };
+    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', action: 'start', details: {}, timestamp: startTime };
+    const activityStart = { id: 'act-1', name: 'DoSomething', kind: 'step', parentId: 'id1', action: 'start', details: {}, timestamp: startTime + 1 };
+    const workflowEnd = { id: 'id1', action: 'end', details: { ok: true }, timestamp: startTime + 2 };
     zRangeMock.mockResolvedValue( [
       JSON.stringify( workflowStart ),
       JSON.stringify( activityStart ),
@@ -97,7 +97,7 @@ describe( 'tracing/processors/s3', () => {
 
     redisMulti.exec.mockResolvedValue( [] );
     const workflowStart = {
-      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, phase: 'start', details: {}, timestamp: startTime
+      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, action: 'start', details: {}, timestamp: startTime
     };
     zRangeMock.mockResolvedValue( [ JSON.stringify( workflowStart ) ] );
 
@@ -113,8 +113,8 @@ describe( 'tracing/processors/s3', () => {
     const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
 
     redisMulti.exec.mockResolvedValue( [] );
-    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', phase: 'start', details: {}, timestamp: startTime };
-    const stepEndNoParent = { id: 'step-1', phase: 'end', details: { done: true }, timestamp: startTime + 1 };
+    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', action: 'start', details: {}, timestamp: startTime };
+    const stepEndNoParent = { id: 'step-1', action: 'end', details: { done: true }, timestamp: startTime + 1 };
     zRangeMock.mockResolvedValue( [
       JSON.stringify( workflowStart ),
       JSON.stringify( stepEndNoParent )
@@ -136,7 +136,7 @@ describe( 'tracing/processors/s3', () => {
 
     redisMulti.exec.mockResolvedValue( [] );
     const workflowEnd = {
-      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, phase: 'end', details: {}, timestamp: startTime
+      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, action: 'end', details: {}, timestamp: startTime
     };
     zRangeMock.mockResolvedValue( [ JSON.stringify( workflowEnd ) ] );
     buildTraceTreeMock.mockReturnValueOnce( null );

package/src/tracing/tools/build_trace_tree.js

@@ -1,3 +1,4 @@
+import { EventAction } from '../trace_consts.js';
 /**
  * @typedef {object} NodeEntry
  * @property {string} id
@@ -27,19 +28,21 @@ const createEntry = id => ( {
   input: undefined,
   output: undefined,
   error: undefined,
-  children: []
+  children: [],
+  attributes: {}
 } );
 
 /**
- * Build a tree of nodes from a list of entries
+ * Builds a tree of nodes from a list of entries.
  *
  * Each node will have: id, name, kind, children, input, output or error, startedAt, endedAt.
  *
- * Entries with same id will be combined according to their phase (start, end OR error).
- * - The details of the start phase becomes input, timestamp becomes startedAt;
- * - The details of the end phase become output, timestamp becomes endedAt;
- * - The details of the error phase become error, timestamp becomes endedAt;
- * - Only start phase's kind and name are used;
+ * Entries with the same id are combined according to their actions.
+ * - The details of the START action become input, and timestamp becomes startedAt;
+ * - The details of the END action become output, timestamp becomes endedAt;
+ * - The details of the ERROR action become error, timestamp becomes endedAt;
+ * - The details of the ADD_ATTR action are attached to `.attributes`;
+ * - Only the START action's `kind` and `name` fields are used;
  *
  *
  * Children are added according to the parentId of each entry.
@@ -53,18 +56,20 @@ export default entries => {
   const ensureNode = id => nodes.get( id ) ?? nodes.set( id, createEntry( id ) ).get( id );
 
   for ( const entry of entries ) {
-    const { kind, id, name, parentId, details, phase, timestamp } = entry;
+    const { kind, id, name, parentId, details, action, timestamp } = entry;
     const node = ensureNode( id );
 
-    if ( phase === 'start' ) {
+    if ( action === EventAction.START ) {
       Object.assign( node, { input: details, startedAt: timestamp, kind, name } );
-    } else if ( phase === 'end' ) {
+    } else if ( action === EventAction.ADD_ATTR ) {
+      node.attributes[details.name] = details.value;
+    } else if ( action === EventAction.END ) {
       Object.assign( node, { output: details, endedAt: timestamp } );
-    } else if ( phase === 'error' ) {
+    } else if ( action === EventAction.ERROR ) {
       Object.assign( node, { error: details, endedAt: timestamp } );
     }
 
-    if ( parentId && phase === 'start' ) {
+    if ( parentId && action === EventAction.START ) {
       const parent = ensureNode( parentId );
       parent.children.push( node );
       parent.children.sort( ( a, b ) => a.startedAt - b.startedAt );

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

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import { EventAction } from '../trace_consts.js';
 import buildTraceTree from './build_trace_tree.js';
 
 describe( 'build_trace_tree', () => {
@@ -6,9 +7,9 @@ describe( 'build_trace_tree', () => {
     expect( buildTraceTree( [] ) ).toBeNull();
   } );
 
-  it( 'sets root output with a fixed message when workflow has no end/error phase yet', () => {
+  it( 'sets root output with a fixed message when workflow has no end/error action yet', () => {
     const entries = [
-      { kind: 'workflow', id: 'wf', parentId: undefined, phase: 'start', name: 'wf', details: {}, timestamp: 1000 }
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 1000 }
     ];
     const result = buildTraceTree( entries );
     expect( result ).not.toBeNull();
@@ -19,17 +20,52 @@ this can indicate it timed out or was interrupted.>>' );
 
   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 }
+      { id: 'a', parentId: 'x', action: EventAction.START, name: 'a', timestamp: 1 },
+      { id: 'b', parentId: 'a', action: EventAction.START, name: 'b', timestamp: 2 }
     ];
     expect( buildTraceTree( entries ) ).toBeNull();
   } );
 
-  it( 'error phase sets error and endedAt on node', () => {
+  it( 'add_attr action merges details.name and details.value into node.attributes', () => {
     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 }
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 100 },
+      { kind: 'step', id: 's', parentId: 'wf', action: EventAction.START, name: 'step', details: {}, timestamp: 200 },
+      { id: 's', action: EventAction.ADD_ATTR, details: { name: 'latency_ms', value: 42 }, timestamp: 250 },
+      { id: 's', action: EventAction.ADD_ATTR, details: { name: 'retries', value: 1 }, timestamp: 260 },
+      { id: 'wf', action: EventAction.END, details: {}, timestamp: 300 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result ).not.toBeNull();
+    expect( result.children[0].attributes ).toEqual( { latency_ms: 42, retries: 1 } );
+  } );
+
+  it( 'add_attr action overwrites prior value for the same attribute name', () => {
+    const entries = [
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 1 },
+      { id: 'wf', action: EventAction.ADD_ATTR, details: { name: 'x', value: 1 }, timestamp: 2 },
+      { id: 'wf', action: EventAction.ADD_ATTR, details: { name: 'x', value: 2 }, timestamp: 3 },
+      { id: 'wf', action: EventAction.END, details: {}, timestamp: 4 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result.attributes ).toEqual( { x: 2 } );
+  } );
+
+  it( 'add_attr does not attach nodes as children (only start does)', () => {
+    const entries = [
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 1 },
+      { id: 'orphan', parentId: 'wf', action: EventAction.ADD_ATTR, details: { name: 'k', value: 'v' }, timestamp: 2 },
+      { id: 'wf', action: EventAction.END, details: {}, timestamp: 3 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result.children ).toHaveLength( 0 );
+    expect( result.attributes ).toEqual( {} );
+  } );
+
+  it( 'error action sets error and endedAt on node', () => {
+    const entries = [
+      { kind: 'wf', id: 'r', parentId: undefined, action: EventAction.START, name: 'root', details: {}, timestamp: 100 },
+      { kind: 'step', id: 's', parentId: 'r', action: EventAction.START, name: 'step', details: {}, timestamp: 200 },
+      { id: 's', action: EventAction.ERROR, details: { message: 'failed' }, timestamp: 300 }
     ];
     const result = buildTraceTree( entries );
     expect( result ).not.toBeNull();
@@ -41,27 +77,28 @@ this can indicate it timed out or was interrupted.>>' );
   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 },
+      { kind: 'workflow', action: EventAction.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 },
+      { kind: 'evaluator', action: EventAction.START, name: 'eval', id: 'eval', parentId: 'wf', details: { z: 0 }, timestamp: 1500 },
+      { id: 'eval', action: EventAction.END, details: { z: 1 }, timestamp: 1600 },
       // step1 start
-      { kind: 'step', phase: 'start', name: 'step-1', id: 's1', parentId: 'wf', details: { x: 1 }, timestamp: 2000 },
+      { kind: 'step', action: EventAction.START, name: 'step-1', id: 's1', parentId: 'wf', details: { x: 1 }, timestamp: 2000 },
+      { id: 's1', action: EventAction.ADD_ATTR, details: { name: 'step_tag', value: 'alpha' }, timestamp: 2050 },
       // IO under step1
-      { kind: 'IO', phase: 'start', name: 'test-1', id: 'io1', parentId: 's1', details: { y: 2 }, timestamp: 2300 },
+      { kind: 'IO', action: EventAction.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 },
+      { kind: 'step', action: EventAction.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 },
+      { kind: 'IO', action: EventAction.START, name: 'test-2', id: 'io2', parentId: 's2', details: { y: 3 }, timestamp: 2500 },
+      { id: 'io2', action: EventAction.END, details: { y: 4 }, timestamp: 2600 },
       // IO under step1 ends
-      { id: 'io1', phase: 'end', details: { y: 5 }, timestamp: 2700 },
+      { id: 'io1', action: EventAction.END, details: { y: 5 }, timestamp: 2700 },
       // step1 end
-      { id: 's1', phase: 'end', details: { done: true }, timestamp: 2800 },
+      { id: 's1', action: EventAction.END, details: { done: true }, timestamp: 2800 },
       // step2 end
-      { id: 's2', phase: 'end', details: { done: true }, timestamp: 2900 },
+      { id: 's2', action: EventAction.END, details: { done: true }, timestamp: 2900 },
       // workflow end
-      { id: 'wf', phase: 'end', details: { ok: true }, timestamp: 3000 }
+      { id: 'wf', action: EventAction.END, details: { ok: true }, timestamp: 3000 }
     ];
 
     const result = buildTraceTree( entries );
@@ -74,6 +111,7 @@ this can indicate it timed out or was interrupted.>>' );
       endedAt: 3000,
       input: { a: 1 },
       output: { ok: true },
+      attributes: {},
       children: [
         {
           id: 'eval',
@@ -83,6 +121,7 @@ this can indicate it timed out or was interrupted.>>' );
           endedAt: 1600,
           input: { z: 0 },
           output: { z: 1 },
+          attributes: {},
           children: []
         },
         {
@@ -93,6 +132,7 @@ this can indicate it timed out or was interrupted.>>' );
           endedAt: 2800,
           input: { x: 1 },
           output: { done: true },
+          attributes: { step_tag: 'alpha' },
           children: [
             {
               id: 'io1',
@@ -102,6 +142,7 @@ this can indicate it timed out or was interrupted.>>' );
               endedAt: 2700,
               input: { y: 2 },
               output: { y: 5 },
+              attributes: {},
               children: []
             }
           ]
@@ -114,6 +155,7 @@ this can indicate it timed out or was interrupted.>>' );
           endedAt: 2900,
           input: { x: 2 },
           output: { done: true },
+          attributes: {},
           children: [
             {
               id: 'io2',
@@ -123,6 +165,7 @@ this can indicate it timed out or was interrupted.>>' );
               endedAt: 2600,
               input: { y: 3 },
               output: { y: 4 },
+              attributes: {},
               children: []
             }
           ]

package/src/tracing/trace_consts.js

@@ -0,0 +1,9 @@
+/**
+ * Each possible action of a trace event
+ */
+export const EventAction = {
+  START: 'start',
+  END: 'end',
+  ERROR: 'error',
+  ADD_ATTR: 'add_attr'
+};

package/src/tracing/trace_engine.js

@@ -64,34 +64,34 @@ export const init = async () => {
 const serializeDetails = details => details instanceof Error ? serializeError( details ) : details;
 
 /**
- * Creates a new trace event phase and sends it to be written
+ * Emits an event action to the event bus.
  *
- * @param {string} phase - The phase
+ * @param {string} action - The action
  * @param {object} fields - All the trace fields
  * @returns {void}
  */
-export const addEventPhase = ( phase, { kind, name, id, parentId, details, executionContext } ) => {
+export const addEventAction = ( action, { 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, timestamp: Date.now(), details: serializeDetails( details ) }
+      entry: { kind, action, name, id, parentId, timestamp: Date.now(), details: serializeDetails( details ) }
     } );
   }
 };
 
 /**
- * Adds an Event Phase, complementing the options with parentId and executionContext from the async storage.
+ * Attaches contextual information to an event action before calling the method to emit it to the bus.
  *
- * 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
+ * This function has no effect if called outside a Temporal Workflow/Activity environment,
+ * so it is safe to use in unit tests or dependencies that might be used elsewhere.
  *
  * @param {object} options - The common trace configurations
  */
-export function addEventPhaseWithContext( phase, options ) {
+export function addEventActionWithContext( action, options ) {
   const storeContent = Storage.load();
-  if ( storeContent ) { // If there is no storageContext this was not called from an Temporal Environment
+  if ( storeContent ) { // If there is no storageContext this was not called from a Temporal environment
     const { parentId, executionContext } = storeContent;
-    addEventPhase( phase, { ...options, parentId, executionContext } );
+    addEventAction( action, { ...options, parentId, executionContext } );
   }
 };

package/src/tracing/trace_engine.spec.js

@@ -39,7 +39,7 @@ describe( 'tracing/trace_engine', () => {
   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();
+    const { init, addEventAction } = await loadTraceEngine();
 
     await init();
 
@@ -47,96 +47,96 @@ describe( 'tracing/trace_engine', () => {
     expect( s3InitMock ).not.toHaveBeenCalled();
 
     const executionContext = { disableTrace: false };
-    addEventPhase( 'start', {
+    addEventAction( '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.action ).toBe( 'start' );
     expect( payload.entry.details ).toEqual( { ok: true } );
     expect( payload.executionContext ).toBe( executionContext );
   } );
 
-  it( 'addEventPhase() emits an entry consumed by processors', async () => {
+  it( 'addEventAction() emits an entry consumed by processors', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = 'on';
-    const { init, addEventPhase } = await loadTraceEngine();
+    const { init, addEventAction } = await loadTraceEngine();
     await init();
 
-    addEventPhase( 'end', {
+    addEventAction( '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.action ).toBe( 'end' );
     expect( payload.entry.details ).toBe( 'done' );
   } );
 
-  it( 'addEventPhase() does not emit when executionContext.disableTrace is true', async () => {
+  it( 'addEventAction() does not emit when executionContext.disableTrace is true', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = '1';
-    const { init, addEventPhase } = await loadTraceEngine();
+    const { init, addEventAction } = await loadTraceEngine();
     await init();
 
-    addEventPhase( 'start', {
+    addEventAction( '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 () => {
+  it( 'addEventAction() does not emit when kind is INTERNAL_STEP', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = '1';
-    const { init, addEventPhase } = await loadTraceEngine();
+    const { init, addEventAction } = await loadTraceEngine();
     await init();
 
-    addEventPhase( 'start', {
+    addEventAction( '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 () => {
+  it( 'addEventActionWithContext() 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();
+    const { init, addEventActionWithContext } = await loadTraceEngine();
     await init();
 
-    addEventPhaseWithContext( 'tick', { kind: 'step', name: 'S', id: '3', details: 1 } );
+    addEventActionWithContext( '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' );
+    expect( payload.entry.action ).toBe( 'tick' );
   } );
 
-  it( 'addEventPhaseWithContext() does not emit when storage executionContext.disableTrace is true', async () => {
+  it( 'addEventActionWithContext() 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();
+    const { init, addEventActionWithContext } = await loadTraceEngine();
     await init();
 
-    addEventPhaseWithContext( 'tick', { kind: 'step', name: 'S', id: '3', details: 1 } );
+    addEventActionWithContext( 'tick', { kind: 'step', name: 'S', id: '3', details: 1 } );
     expect( localExecMock ).not.toHaveBeenCalled();
   } );
 
-  it( 'addEventPhaseWithContext() is a no-op when storage is absent', async () => {
+  it( 'addEventActionWithContext() is a no-op when storage is absent', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = '1';
     storageLoadMock.mockReturnValue( undefined );
-    const { init, addEventPhaseWithContext } = await loadTraceEngine();
+    const { init, addEventActionWithContext } = await loadTraceEngine();
     await init();
 
-    addEventPhaseWithContext( 'noop', { kind: 'step', name: 'X', id: '4', details: null } );
+    addEventActionWithContext( 'noop', { kind: 'step', name: 'X', id: '4', details: null } );
     expect( localExecMock ).not.toHaveBeenCalled();
   } );