@outputai/core 0.4.1-dev.7b85c96.0 → 0.4.1-dev.ae4bd16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.4.1-dev.7b85c96.0",
+  "version": "0.4.1-dev.ae4bd16.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -43,6 +43,7 @@
     "@temporalio/common": "1.17.0",
     "@temporalio/worker": "1.17.0",
     "@temporalio/workflow": "1.17.0",
+    "decimal.js": "10.6.0",
     "json-stream-stringify": "3.1.6",
     "redis": "5.12.1",
     "stacktrace-parser": "0.1.11",
@@ -66,6 +67,7 @@
     "#logger": "./src/logger.js",
     "#utils": "./src/utils/index.js",
     "#tracing": "./src/tracing/internal_interface.js",
+    "#trace_attribute": "./src/tracing/trace_attribute.js",
     "#async_storage": "./src/async_storage.js",
     "#internal_activities": "./src/internal_activities/index.js"
   },

package/src/activity_integration/tracing.d.ts

@@ -1,3 +1,6 @@
+import type { Attribute } from '#trace_attribute';
+
+export { Attribute } from '#trace_attribute';
 /**
  * Creates a new event.
  *
@@ -32,14 +35,6 @@ export declare function addEventError( args: { id: string; details: unknown } ):
  *
  * @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.
+ * @param args.attribute - The attribute to attach to the event.
  */
-export declare const Attribute: {
-  COST: 'cost';
-};
+export declare function addEventAttribute( args: { eventId: string; attribute: Attribute.Instance } ): void;

package/src/activity_integration/tracing.js

@@ -1,5 +1,7 @@
 import { addEventActionWithContext, EventAction } from '#tracing';
 
+export { Attribute } from '#trace_attribute';
+
 /**
  * Creates a new event.
  *
@@ -42,12 +44,5 @@ export const addEventError = ( { id, details } ) => addEventActionWithContext( E
  * @param {unknown} args.value - The attribute value
  * @returns {void}
  */
-export const addEventAttribute = ( { eventId, name, value } ) =>
-  addEventActionWithContext( EventAction.ADD_ATTR, { id: eventId, details: { name, value } } );
-
-/**
- * Known attributes
- */
-export const Attribute = {
-  COST: 'cost'
-};
+export const addEventAttribute = ( { eventId, attribute } ) =>
+  addEventActionWithContext( EventAction.ADD_ATTR, { id: eventId, details: attribute } );

package/src/consts.js

@@ -33,6 +33,10 @@ export const BusEventType = {
   RUNTIME_ERROR: 'runtime_error'
 };
 
+export const Signal = {
+  ADD_ATTRIBUTE: 'add_attribute'
+};
+
 export const WorkflowSpecialOutput = {
   CONTINUED_AS_NEW: '<<continued_as_new>>'
 };

package/src/hooks/index.d.ts

@@ -123,8 +123,8 @@ export interface HttpRequestHookPayload {
   status?: number;
   /** Elapsed time from request issuance to response (or failure), in milliseconds. */
   durationMs: number;
-  /** Outcome bucket: `success` (2xx-3xx), `http_error` (>=400), `network_error` (DNS / timeout / abort). */
-  outcome: 'success' | 'http_error' | 'network_error';
+  /** Outcome bucket: `success` (2xx-3xx), `error` (status >= 400), `failure` (DNS / timeout / abort). */
+  outcome: 'success' | 'error' | 'failure';
 }
 
 /**

package/src/interface/aggregations.js

@@ -0,0 +1,24 @@
+import { Attribute } from '#trace_attribute';
+import Decimal from 'decimal.js';
+
+export const aggregateAttributes = attributes => ( {
+  cost: {
+    total: attributes
+      .filter( a => [ Attribute.HTTPRequestCost.TYPE, Attribute.LLMUsage.TYPE ].includes( a.type ) )
+      .reduce( ( sum, a ) => sum.add( a.total ), Decimal( 0 ) ).toNumber()
+  },
+  tokens: {
+    total: attributes
+      .filter( a => Attribute.LLMUsage.TYPE === a.type )
+      .reduce( ( sum, a ) => sum.add( a.tokensUsed ), Decimal( 0 ) ).toNumber(),
+    ...Object.entries( attributes
+      .filter( a => Attribute.LLMUsage.TYPE === a.type )
+      .flatMap( a => a.usage )
+      .reduce( ( obj, a ) => Object.assign( obj, { [a.type]: ( obj[a.type] ?? Decimal( 0 ) ).add( a.amount ) } ), {} ) )
+      .reduce( ( obj, [ k, v ] ) => Object.assign( obj, { [k]: v.toNumber() } ), {} ) // convert all values to number
+
+  },
+  httpRequests: {
+    total: attributes.filter( a => Attribute.HTTPRequestCount.TYPE === a.type ).length
+  }
+} );

package/src/interface/aggregations.spec.js

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { Attribute } from '#trace_attribute';
+import { aggregateAttributes } from './aggregations.js';
+
+describe( 'aggregateAttributes', () => {
+  it( 'returns zeroed aggregations when there are no attributes', () => {
+    expect( aggregateAttributes( [] ) ).toEqual( {
+      cost: { total: 0 },
+      tokens: { total: 0 },
+      httpRequests: { total: 0 }
+    } );
+  } );
+
+  it( 'aggregates costs, token usage, and HTTP request count by attribute type', () => {
+    const attributes = [
+      {
+        type: Attribute.HTTPRequestCount.TYPE,
+        url: 'https://api.example.test/a',
+        requestId: 'req-1'
+      },
+      {
+        type: Attribute.HTTPRequestCount.TYPE,
+        url: 'https://api.example.test/b',
+        requestId: 'req-2'
+      },
+      {
+        type: Attribute.HTTPRequestCost.TYPE,
+        url: 'https://api.example.test/a',
+        requestId: 'req-1',
+        total: 0.2
+      },
+      {
+        type: Attribute.LLMUsage.TYPE,
+        modelId: 'gpt-4o',
+        total: 0.3,
+        tokensUsed: 120,
+        usage: [
+          { type: 'input', ppm: 1, amount: 100, total: 0.1 },
+          { type: 'output', ppm: 2, amount: 20, total: 0.2 }
+        ]
+      },
+      {
+        type: Attribute.LLMUsage.TYPE,
+        modelId: 'gpt-4o-mini',
+        total: 0.05,
+        tokensUsed: 30,
+        usage: [
+          { type: 'input', ppm: 1, amount: 25, total: 0.025 },
+          { type: 'reasoning', ppm: 5, amount: 5, total: 0.025 }
+        ]
+      },
+      {
+        type: 'unrelated',
+        total: 100,
+        tokensUsed: 100
+      }
+    ];
+
+    expect( aggregateAttributes( attributes ) ).toEqual( {
+      cost: { total: 0.55 },
+      tokens: {
+        total: 150,
+        input: 125,
+        output: 20,
+        reasoning: 5
+      },
+      httpRequests: { total: 2 }
+    } );
+  } );
+
+  it( 'uses LLMUsage.tokensUsed for total tokens instead of summing usage amounts', () => {
+    const attributes = [
+      {
+        type: Attribute.LLMUsage.TYPE,
+        modelId: 'provider-model',
+        total: 0.1,
+        tokensUsed: 42,
+        usage: [
+          { type: 'input', ppm: 1, amount: 10, total: 0.01 },
+          { type: 'output', ppm: 1, amount: 5, total: 0.005 }
+        ]
+      }
+    ];
+
+    expect( aggregateAttributes( attributes ).tokens ).toEqual( {
+      total: 42,
+      input: 10,
+      output: 5
+    } );
+  } );
+} );

package/src/interface/workflow.js

@@ -1,11 +1,13 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy, continueAsNew } from '@temporalio/workflow';
+import { defineSignal, setHandler } from '@temporalio/workflow';
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
-import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS, METADATA_ACCESS_SYMBOL } from '#consts';
+import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS, METADATA_ACCESS_SYMBOL, Signal } from '#consts';
 import { deepMerge, setMetadata, toUrlSafeBase64 } from '#utils';
 import { FatalError, ValidationError } from '#errors';
 import { Context } from './workflow_context.js';
+import { aggregateAttributes } from './aggregations.js';
 
 const defaultOptions = {
   activityOptions: {
@@ -22,6 +24,9 @@ const defaultOptions = {
   disableTrace: false
 };
 
+export const extractErrorDetail = ( e, key ) =>
+  e ? ( e.details?.find?.( d => d[key] )?.[key] ?? extractErrorDetail( e.cause, key ) ) : null;
+
 export function workflow( { name, description, inputSchema, outputSchema, fn, options = {}, aliases = [] } ) {
   validateWorkflow( { name, description, inputSchema, outputSchema, fn, options, aliases } );
 
@@ -75,7 +80,9 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
 
     // Run the internal activity to retrieve the workflow trace destinations (only for root workflows, not nested)
     const traceDestinations = isRoot ? ( await steps[ACTIVITY_GET_TRACE_DESTINATIONS]( executionContext ) ) : null;
-    const traceObject = { trace: { destinations: traceDestinations } };
+
+    const attributes = [];
+    setHandler( defineSignal( Signal.ADD_ATTRIBUTE ), e => attributes.push( e ) );
 
     try {
       // validation comes after setting memo to have that info already set for interceptor even if validations fail
@@ -97,17 +104,25 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
          * @param {import('@temporalio/workflow').ActivityOptions} extra.options
          * @returns {Promise<unknown>}
          */
-        startWorkflow: async ( childName, input, extra = {} ) =>
-          executeChild( childName, {
-            args: input ? [ input ] : [],
-            workflowId: `${workflowId}-${toUrlSafeBase64( uuid4() )}`,
-            parentClosePolicy: ParentClosePolicy[extra?.detached ? 'ABANDON' : 'TERMINATE'],
-            memo: {
-              executionContext,
-              parentId: workflowId,
-              ...( extra?.options?.activityOptions && { activityOptions: deepMerge( activityOptions, extra.options.activityOptions ) } )
-            }
-          } )
+        startWorkflow: async ( childName, input, extra = {} ) => {
+          try {
+            const result = await executeChild( childName, {
+              args: input ? [ input ] : [],
+              workflowId: `${workflowId}-${toUrlSafeBase64( uuid4() )}`,
+              parentClosePolicy: ParentClosePolicy[extra?.detached ? 'ABANDON' : 'TERMINATE'],
+              memo: {
+                executionContext,
+                parentId: workflowId,
+                ...( extra?.options?.activityOptions && { activityOptions: deepMerge( activityOptions, extra.options.activityOptions ) } )
+              }
+            } );
+            attributes.push( ...( result.attributes ?? [] ) );
+            return result.output;
+          } catch ( error ) {
+            attributes.push( ...( extractErrorDetail( error, 'attributes' ) ?? [] ) );
+            throw error;
+          }
+        }
       };
 
       const output = await fn.call( dispatchers, input, context );
@@ -116,14 +131,17 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
 
       if ( isRoot ) {
         // Append the trace info to the result of the workflow
-        return { output, ...traceObject };
+        return { output, trace: { destinations: traceDestinations }, attributes, aggregations: aggregateAttributes( attributes ) };
       }
 
-      return output;
+      return { output, attributes };
     } catch ( e ) {
-      // Append the trace info as metadata of the error, so it can be read by the interceptor.
+      // Append the extra info as metadata of the error, so it can be read by the interceptor.
+      e[METADATA_ACCESS_SYMBOL] = { ...( e[METADATA_ACCESS_SYMBOL] ?? {} ), attributes };
+      // if it is roo also add trace/aggregations
       if ( isRoot ) {
-        e[METADATA_ACCESS_SYMBOL] = { ...( e[METADATA_ACCESS_SYMBOL] ?? {} ), ...traceObject };
+        e[METADATA_ACCESS_SYMBOL].trace = { destinations: traceDestinations };
+        e[METADATA_ACCESS_SYMBOL].aggregations = aggregateAttributes( attributes );
       }
       throw e;
     }

package/src/interface/workflow.spec.js

@@ -1,7 +1,10 @@
+import { Signal } from '#consts';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { z } from 'zod';
 
 const inWorkflowContextMock = vi.hoisted( () => vi.fn( () => true ) );
+const defineSignalMock = vi.hoisted( () => vi.fn( name => name ) );
+const setHandlerMock = vi.hoisted( () => vi.fn() );
 const traceDestinationsStepMock = vi.fn().mockResolvedValue( { local: '/tmp/trace' } );
 const executeChildMock = vi.fn().mockResolvedValue( undefined );
 const continueAsNewMock = vi.fn().mockResolvedValue( undefined );
@@ -41,7 +44,16 @@ vi.mock( '@temporalio/workflow', () => ( {
   workflowInfo: workflowInfoMock,
   uuid4: () => '550e8400e29b41d4a716446655440000',
   ParentClosePolicy: { TERMINATE: 'TERMINATE', ABANDON: 'ABANDON' },
-  continueAsNew: continueAsNewMock
+  ChildWorkflowFailure: class ChildWorkflowFailure extends Error {
+    constructor( message, cause ) {
+      super( message );
+      this.name = 'ChildWorkflowFailure';
+      this.cause = cause;
+    }
+  },
+  continueAsNew: continueAsNewMock,
+  defineSignal: ( ...args ) => defineSignalMock( ...args ),
+  setHandler: ( ...args ) => setHandlerMock( ...args )
 } ) );
 
 vi.mock( '#consts', async importOriginal => {
@@ -53,10 +65,17 @@ vi.mock( '#consts', async importOriginal => {
   };
 } );
 
+const emptyAggregations = {
+  cost: { total: 0 },
+  tokens: { total: 0 },
+  httpRequests: { total: 0 }
+};
+
 describe( 'workflow()', () => {
   beforeEach( () => {
     vi.clearAllMocks();
     inWorkflowContextMock.mockReturnValue( true );
+    defineSignalMock.mockImplementation( name => name );
     workflowInfoMock.mockReturnValue( { ...workflowInfoReturn } );
     workflowInfoReturn.memo = {};
     proxyActivitiesMock.mockImplementation( () => {
@@ -217,7 +236,7 @@ describe( 'workflow()', () => {
   } );
 
   describe( 'root workflow (in workflow context)', () => {
-    it( 'calls getTraceDestinations, returns { output, trace } and assigns executionContext to memo', async () => {
+    it( 'calls getTraceDestinations, returns root trace data and assigns executionContext to memo', async () => {
       const { workflow } = await import( './workflow.js' );
 
       const wf = workflow( {
@@ -232,7 +251,9 @@ describe( 'workflow()', () => {
       expect( traceDestinationsStepMock ).toHaveBeenCalledTimes( 1 );
       expect( result ).toEqual( {
         output: { v: 42 },
-        trace: { destinations: { local: '/tmp/trace' } }
+        trace: { destinations: { local: '/tmp/trace' } },
+        attributes: [],
+        aggregations: emptyAggregations
       } );
       const memo = workflowInfoMock().memo;
       expect( memo.executionContext ).toEqual( {
@@ -243,6 +264,68 @@ describe( 'workflow()', () => {
       } );
     } );
 
+    it( 'collects attribute signals and returns aggregated attributes', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const { Attribute } = await import( '#trace_attribute' );
+      const handlers = { addAttribute: () => {} };
+      setHandlerMock.mockImplementation( ( signalName, handler ) => {
+        if ( signalName === Signal.ADD_ATTRIBUTE ) {
+          handlers.addAttribute = handler;
+        }
+      } );
+
+      const httpRequest = {
+        type: Attribute.HTTPRequestCount.TYPE,
+        url: 'https://api.example.test/items',
+        requestId: 'req-1'
+      };
+      const httpCost = {
+        type: Attribute.HTTPRequestCost.TYPE,
+        url: 'https://api.example.test/items',
+        requestId: 'req-1',
+        total: 2.5
+      };
+      const llmUsage = {
+        type: Attribute.LLMUsage.TYPE,
+        modelId: 'gpt-4o',
+        total: 0.25,
+        usage: [
+          { type: 'input', ppm: 5, amount: 20_000, total: 0.1 },
+          { type: 'output', ppm: 30, amount: 5_000, total: 0.15 }
+        ],
+        tokensUsed: 25_000
+      };
+
+      const wf = workflow( {
+        name: 'attr_wf',
+        description: 'Attributes',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( { ok: z.boolean() } ),
+        fn: async () => {
+          handlers.addAttribute( httpRequest );
+          handlers.addAttribute( httpCost );
+          handlers.addAttribute( llmUsage );
+          return { ok: true };
+        }
+      } );
+
+      const result = await wf( {} );
+      expect( result ).toEqual( {
+        output: { ok: true },
+        trace: { destinations: { local: '/tmp/trace' } },
+        attributes: [ httpRequest, httpCost, llmUsage ],
+        aggregations: {
+          cost: { total: 2.75 },
+          tokens: {
+            total: 25_000,
+            input: 20_000,
+            output: 5_000
+          },
+          httpRequests: { total: 1 }
+        }
+      } );
+    } );
+
     it( 'sets executionContext.disableTrace when options.disableTrace is true', async () => {
       const { workflow } = await import( './workflow.js' );
 
@@ -261,7 +344,7 @@ describe( 'workflow()', () => {
   } );
 
   describe( 'child workflow (memo.executionContext already set)', () => {
-    it( 'does not call getTraceDestinations and returns plain output', async () => {
+    it( 'does not call getTraceDestinations and returns an internal output envelope', async () => {
       workflowInfoMock.mockReturnValue( {
         ...workflowInfoReturn,
         memo: { executionContext: { workflowId: 'parent-1', workflowName: 'parent_wf' } }
@@ -278,7 +361,7 @@ describe( 'workflow()', () => {
 
       const result = await wf( {} );
       expect( traceDestinationsStepMock ).not.toHaveBeenCalled();
-      expect( result ).toEqual( { x: 'child' } );
+      expect( result ).toEqual( { output: { x: 'child' }, attributes: [] } );
     } );
   } );
 
@@ -381,6 +464,7 @@ describe( 'workflow()', () => {
     it( 'calls executeChild with correct args and TERMINATE when not detached', async () => {
       const { workflow } = await import( './workflow.js' );
       const { ParentClosePolicy } = await import( '@temporalio/workflow' );
+      executeChildMock.mockResolvedValueOnce( { output: {}, attributes: [] } );
 
       const wf = workflow( {
         name: 'parent_wf',
@@ -408,6 +492,7 @@ describe( 'workflow()', () => {
     it( 'uses ABANDON when extra.detached is true', async () => {
       const { workflow } = await import( './workflow.js' );
       const { ParentClosePolicy } = await import( '@temporalio/workflow' );
+      executeChildMock.mockResolvedValueOnce( { output: {}, attributes: [] } );
 
       const wf = workflow( {
         name: 'detach_wf',
@@ -428,6 +513,7 @@ describe( 'workflow()', () => {
 
     it( 'passes empty args when input is null/omitted', async () => {
       const { workflow } = await import( './workflow.js' );
+      executeChildMock.mockResolvedValueOnce( { output: {}, attributes: [] } );
 
       const wf = workflow( {
         name: 'no_input_wf',
@@ -445,11 +531,96 @@ describe( 'workflow()', () => {
         args: []
       } ) );
     } );
+
+    it( 'returns child output and merges child attributes into the root result', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const { Attribute } = await import( '#trace_attribute' );
+      const childAttribute = {
+        type: Attribute.LLMUsage.TYPE,
+        modelId: 'gpt-4o',
+        total: 0.4,
+        tokensUsed: 20,
+        usage: [
+          { type: 'input', ppm: 10, amount: 20, total: 0.4 }
+        ]
+      };
+      executeChildMock.mockResolvedValueOnce( {
+        output: { child: 'ok' },
+        attributes: [ childAttribute ]
+      } );
+
+      const wf = workflow( {
+        name: 'merge_child_wf',
+        description: 'Merge child attributes',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( { child: z.string() } ),
+        async fn() {
+          return this.startWorkflow( 'child_wf', { id: 1 } );
+        }
+      } );
+
+      const result = await wf( {} );
+      expect( result ).toEqual( {
+        output: { child: 'ok' },
+        trace: { destinations: { local: '/tmp/trace' } },
+        attributes: [ childAttribute ],
+        aggregations: {
+          cost: { total: 0.4 },
+          tokens: {
+            total: 20,
+            input: 20
+          },
+          httpRequests: { total: 0 }
+        }
+      } );
+    } );
+
+    it( 'merges child error attributes before rethrowing to root metadata', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const { ChildWorkflowFailure } = await import( '@temporalio/workflow' );
+      const { METADATA_ACCESS_SYMBOL } = await import( '#consts' );
+      const { Attribute } = await import( '#trace_attribute' );
+      const childAttribute = {
+        type: Attribute.HTTPRequestCost.TYPE,
+        url: 'https://api.example.test',
+        requestId: 'req-child',
+        total: 2
+      };
+      const childError = new ChildWorkflowFailure( 'child failed', {
+        message: 'Child workflow execution failed',
+        details: [ { attributes: [ childAttribute ] } ]
+      } );
+      executeChildMock.mockRejectedValueOnce( childError );
+
+      const wf = workflow( {
+        name: 'child_error_wf',
+        description: 'Child error attributes',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        async fn() {
+          await this.startWorkflow( 'child_wf', { id: 1 } );
+          return {};
+        }
+      } );
+
+      await expect( wf( {} ) ).rejects.toThrow( 'child failed' );
+      expect( childError[METADATA_ACCESS_SYMBOL] ).toEqual( {
+        attributes: [ childAttribute ],
+        trace: { destinations: { local: '/tmp/trace' } },
+        aggregations: {
+          cost: { total: 2 },
+          tokens: { total: 0 },
+          httpRequests: { total: 0 }
+        }
+      } );
+    } );
   } );
 
   describe( 'error handling (root workflow)', () => {
-    it( 'rethrows error from fn and rejects with same message', async () => {
+    it( 'rethrows error from fn with trace attributes and aggregation metadata', async () => {
       const { workflow } = await import( './workflow.js' );
+      const { METADATA_ACCESS_SYMBOL } = await import( '#consts' );
+      const error = new Error( 'workflow failed' );
 
       const wf = workflow( {
         name: 'err_wf',
@@ -457,11 +628,16 @@ describe( 'workflow()', () => {
         inputSchema: z.object( {} ),
         outputSchema: z.object( {} ),
         fn: async () => {
-          throw new Error( 'workflow failed' );
+          throw error;
         }
       } );
 
       await expect( wf( {} ) ).rejects.toThrow( 'workflow failed' );
+      expect( error[METADATA_ACCESS_SYMBOL] ).toEqual( {
+        trace: { destinations: { local: '/tmp/trace' } },
+        attributes: [],
+        aggregations: emptyAggregations
+      } );
     } );
   } );
 } );

package/src/tracing/tools/build_trace_tree.js

@@ -62,7 +62,7 @@ export default entries => {
     if ( action === EventAction.START ) {
       Object.assign( node, { input: details, startedAt: timestamp, kind, name } );
     } else if ( action === EventAction.ADD_ATTR ) {
-      node.attributes[details.name] = details.value;
+      node.attributes[details.type] = details;
     } else if ( action === EventAction.END ) {
       Object.assign( node, { output: details, endedAt: timestamp } );
     } else if ( action === EventAction.ERROR ) {

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

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { EventAction } from '../trace_consts.js';
+import { Attribute } from '#trace_attribute';
 import buildTraceTree from './build_trace_tree.js';
 
 describe( 'build_trace_tree', () => {
@@ -26,34 +27,66 @@ this can indicate it timed out or was interrupted.>>' );
     expect( buildTraceTree( entries ) ).toBeNull();
   } );
 
-  it( 'add_attr action merges details.name and details.value into node.attributes', () => {
+  it( 'add_attr action stores attribute details by type on node.attributes', () => {
+    const requestCount = {
+      type: Attribute.HTTPRequestCount.TYPE,
+      url: 'https://api.example.test',
+      requestId: 'req-1'
+    };
+    const requestCost = {
+      type: Attribute.HTTPRequestCost.TYPE,
+      url: 'https://api.example.test',
+      requestId: 'req-1',
+      total: 0.2
+    };
     const entries = [
       { 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: 's', action: EventAction.ADD_ATTR, details: requestCount, timestamp: 250 },
+      { id: 's', action: EventAction.ADD_ATTR, details: requestCost, 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 } );
+    expect( result.children[0].attributes ).toEqual( {
+      [Attribute.HTTPRequestCount.TYPE]: requestCount,
+      [Attribute.HTTPRequestCost.TYPE]: requestCost
+    } );
   } );
 
-  it( 'add_attr action overwrites prior value for the same attribute name', () => {
+  it( 'add_attr action overwrites prior value for the same attribute type', () => {
+    const firstCost = {
+      type: Attribute.HTTPRequestCost.TYPE,
+      url: 'https://api.example.test',
+      requestId: 'req-1',
+      total: 1
+    };
+    const secondCost = {
+      type: Attribute.HTTPRequestCost.TYPE,
+      url: 'https://api.example.test',
+      requestId: 'req-1',
+      total: 2
+    };
     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.ADD_ATTR, details: firstCost, timestamp: 2 },
+      { id: 'wf', action: EventAction.ADD_ATTR, details: secondCost, timestamp: 3 },
       { id: 'wf', action: EventAction.END, details: {}, timestamp: 4 }
     ];
     const result = buildTraceTree( entries );
-    expect( result.attributes ).toEqual( { x: 2 } );
+    expect( result.attributes ).toEqual( { [Attribute.HTTPRequestCost.TYPE]: secondCost } );
   } );
 
   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: 'orphan',
+        parentId: 'wf',
+        action: EventAction.ADD_ATTR,
+        details: { type: Attribute.HTTPRequestCount.TYPE, url: 'https://api.example.test', requestId: 'req-1' },
+        timestamp: 2
+      },
       { id: 'wf', action: EventAction.END, details: {}, timestamp: 3 }
     ];
     const result = buildTraceTree( entries );
@@ -75,6 +108,11 @@ this can indicate it timed out or was interrupted.>>' );
   } );
 
   it( 'builds a tree from workflow/step/IO entries with grouping and sorting', () => {
+    const stepAttribute = {
+      type: Attribute.HTTPRequestCount.TYPE,
+      url: 'https://api.example.test/step-1',
+      requestId: 'req-step-1'
+    };
     const entries = [
       // workflow start
       { kind: 'workflow', action: EventAction.START, name: 'wf', id: 'wf', parentId: undefined, details: { a: 1 }, timestamp: 1000 },
@@ -83,7 +121,7 @@ this can indicate it timed out or was interrupted.>>' );
       { id: 'eval', action: EventAction.END, details: { z: 1 }, timestamp: 1600 },
       // step1 start
       { 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 },
+      { id: 's1', action: EventAction.ADD_ATTR, details: stepAttribute, timestamp: 2050 },
       // IO under step1
       { kind: 'IO', action: EventAction.START, name: 'test-1', id: 'io1', parentId: 's1', details: { y: 2 }, timestamp: 2300 },
       // step2 start
@@ -132,7 +170,7 @@ this can indicate it timed out or was interrupted.>>' );
           endedAt: 2800,
           input: { x: 1 },
           output: { done: true },
-          attributes: { step_tag: 'alpha' },
+          attributes: { [Attribute.HTTPRequestCount.TYPE]: stepAttribute },
           children: [
             {
               id: 'io1',

package/src/tracing/trace_attribute.d.ts

@@ -0,0 +1,38 @@
+export declare namespace Attribute {
+  export interface Usage {
+    type: string;
+    ppm: number;
+    amount: number;
+    total: number;
+  }
+
+  export class HTTPRequestCount {
+    static TYPE: 'http:request:count';
+    type: typeof HTTPRequestCount.TYPE;
+    url: string;
+    requestId: string;
+    constructor( url: string, requestId: string );
+  }
+
+  export class HTTPRequestCost {
+    static TYPE: 'http:request:cost';
+    type: typeof HTTPRequestCost.TYPE;
+    url: string;
+    requestId: string;
+    total: number;
+    constructor( url: string, requestId: string, total: number );
+  }
+
+  export class LLMUsage {
+    static TYPE: 'llm:usage';
+    type: typeof LLMUsage.TYPE;
+    modelId: string;
+    usage: Usage[];
+    constructor( modelId: string );
+    addUsage( usage: { type: string; ppm: number; amount: number } ): void;
+    readonly total: number;
+    readonly tokensUsed: number;
+  }
+
+  export type Instance = HTTPRequestCount | HTTPRequestCost | LLMUsage;
+}

package/src/tracing/trace_attribute.js

@@ -0,0 +1,80 @@
+import Decimal from 'decimal.js';
+
+/**
+ * All attributes inherit from this
+ */
+export class BaseAttribute {
+  activityId;
+  activityName;
+  date = Date.now();
+  type;
+
+  constructor( type ) {
+    this.type = type;
+  }
+
+  setActivity( id, name ) {
+    this.activityId = id;
+    this.activityName = name;
+  }
+}
+
+class HTTPRequestCount extends BaseAttribute {
+  static TYPE = 'http:request:count';
+  url;
+  requestId;
+
+  constructor( url, requestId ) {
+    super( HTTPRequestCount.TYPE );
+    this.url = url;
+    this.requestId = requestId;
+  }
+}
+
+class HTTPRequestCost extends BaseAttribute {
+  static TYPE = 'http:request:cost';
+  url;
+  requestId;
+  total = 0;
+
+  constructor( url, requestId, total ) {
+    super( HTTPRequestCost.TYPE );
+    this.url = url;
+    this.requestId = requestId;
+    this.total = total;
+  }
+}
+
+class LLMUsage extends BaseAttribute {
+  static TYPE = 'llm:usage';
+  modelId;
+  usage = [];
+  total = 0;
+  tokensUsed = 0;
+
+  constructor( modelId ) {
+    super( LLMUsage.TYPE );
+    this.modelId = modelId;
+  }
+
+  addUsage( { type, ppm, amount } ) {
+    const total = Decimal( amount ).div( 1_000_000 ).mul( ppm ).toNumber();
+    this.usage.push( {
+      type,
+      ppm,
+      amount,
+      total
+    } );
+    this.total = Decimal( this.total ).add( total ).toNumber();
+    this.tokensUsed = Decimal( this.tokensUsed ).add( amount ).toNumber();
+  }
+}
+
+/**
+ * Types of ADD_ATTR attributes
+ */
+export const Attribute = {
+  LLMUsage,
+  HTTPRequestCost,
+  HTTPRequestCount
+};

package/src/tracing/trace_engine.js

@@ -4,8 +4,10 @@ import { serializeError } from './tools/utils.js';
 import { isStringboolTrue } from '#utils';
 import * as localProcessor from './processors/local/index.js';
 import * as s3Processor from './processors/s3/index.js';
-import { ComponentType } from '#consts';
+import { ComponentType, Signal } from '#consts';
 import { createChildLogger } from '#logger';
+import { EventAction } from './trace_consts.js';
+import { BaseAttribute } from './trace_attribute.js';
 
 const log = createChildLogger( 'Tracing' );
 
@@ -91,7 +93,15 @@ export const addEventAction = ( action, { kind, name, id, parentId, details, exe
 export function addEventActionWithContext( action, options ) {
   const storeContent = Storage.load();
   if ( storeContent ) { // If there is no storageContext this was not called from a Temporal environment
-    const { parentId, executionContext } = storeContent;
+    const { parentId, parentName, executionContext, workflowHandle } = storeContent;
+    if ( action === EventAction.ADD_ATTR ) {
+      const attribute = options.details;
+      if ( !( attribute instanceof BaseAttribute ) ) {
+        throw new Error( `${EventAction.ADD_ATTR} called argument that is not a BaseAttribute instance` );
+      }
+      attribute.setActivity( parentId, parentName );
+      workflowHandle.signal( Signal.ADD_ATTRIBUTE, attribute );
+    }
     addEventAction( action, { ...options, parentId, executionContext } );
   }
 };

package/src/worker/index.js

@@ -69,7 +69,7 @@ const callerDir = process.argv[2];
     workflowsPath,
     activities,
     sinks,
-    interceptors: initInterceptors( { activities, workflows } ),
+    interceptors: initInterceptors( { activities, workflows, connection } ),
     maxConcurrentWorkflowTaskExecutions,
     maxConcurrentActivityTaskExecutions,
     maxCachedWorkflows,

package/src/worker/index.spec.js

@@ -123,7 +123,7 @@ describe( 'worker/index', () => {
       maxConcurrentActivityTaskPolls: configValues.maxConcurrentActivityTaskPolls,
       maxConcurrentWorkflowTaskPolls: configValues.maxConcurrentWorkflowTaskPolls
     } ) );
-    expect( initInterceptorsMock ).toHaveBeenCalledWith( { activities: {}, workflows: [] } );
+    expect( initInterceptorsMock ).toHaveBeenCalledWith( { activities: {}, workflows: [], connection: mockConnection } );
     expect( registerShutdownMock ).toHaveBeenCalledWith( { worker: mockWorker, log: mockLog } );
     expect( startCatalogMock ).toHaveBeenCalledWith( {
       connection: mockConnection,

package/src/worker/interceptors/activity.js

@@ -5,6 +5,7 @@ import { headersToObject } from '../sandboxed_utils.js';
 import { BusEventType, METADATA_ACCESS_SYMBOL } from '#consts';
 import { activityHeartbeatEnabled, activityHeartbeatIntervalMs } from '../configs.js';
 import { messageBus } from '#bus';
+import { Client } from '@temporalio/client';
 
 /*
   This interceptor wraps every activity execution with cross-cutting concerns:
@@ -23,7 +24,7 @@ import { messageBus } from '#bus';
   - Headers injected by the workflow interceptor (executionContext)
 */
 export class ActivityExecutionInterceptor {
-  constructor( { activities, workflows } ) {
+  constructor( { activities, workflows, connection } ) {
     this.activities = activities;
     this.workflowsMap = workflows.reduce( ( map, w ) => {
       map.set( w.name, w );
@@ -32,14 +33,19 @@ export class ActivityExecutionInterceptor {
       }
       return map;
     }, new Map() );
+    this.connection = connection;
   };
 
   async execute( input, next ) {
     const startDate = Date.now();
+    const client = new Client( { connection: this.connection } );
+
     const { workflowExecution: { workflowId }, activityId: id, activityType: name, workflowType: workflowName } = Context.current().info;
     const { executionContext } = headersToObject( input.headers );
     const { type: kind } = this.activities?.[name]?.[METADATA_ACCESS_SYMBOL];
 
+    const workflowHandle = client.workflow.getHandle( workflowId );
+
     messageBus.emit( BusEventType.ACTIVITY_START, { id, name, kind, workflowId, workflowName } );
     Tracing.addEventStart( { id, name, kind, parentId: workflowId, details: input.args[0], executionContext } );
 
@@ -56,7 +62,8 @@ export class ActivityExecutionInterceptor {
       intervals.heartbeat = activityHeartbeatEnabled && setInterval( () => Context.current().heartbeat(), activityHeartbeatIntervalMs );
 
       // Wraps the execution with accessible metadata for the activity
-      const output = await Storage.runWithContext( async _ => next( input ), { parentId: id, executionContext, workflowFilename } );
+      const ctx = { parentId: id, parentName: name, executionContext, workflowFilename, workflowHandle };
+      const output = await Storage.runWithContext( async _ => next( input ), ctx );
 
       messageBus.emit( BusEventType.ACTIVITY_END, { id, name, kind, workflowId, workflowName, duration: Date.now() - startDate } );
       Tracing.addEventEnd( { id, details: output, executionContext } );

package/src/worker/interceptors/activity.spec.js

@@ -2,6 +2,8 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { BusEventType } from '#consts';
 
 const METADATA_ACCESS_SYMBOL = vi.hoisted( () => Symbol( '__metadata' ) );
+const workflowHandleMock = vi.hoisted( () => ( { signal: vi.fn() } ) );
+const getHandleMock = vi.hoisted( () => vi.fn( () => workflowHandleMock ) );
 
 const heartbeatMock = vi.fn();
 const runWithContextMock = vi.hoisted( () => vi.fn().mockImplementation( async fn => fn() ) );
@@ -21,6 +23,14 @@ vi.mock( '@temporalio/activity', () => ( {
   }
 } ) );
 
+vi.mock( '@temporalio/client', () => ( {
+  Client: class Client {
+    workflow = {
+      getHandle: getHandleMock
+    };
+  }
+} ) );
+
 vi.mock( '#async_storage', () => ( {
   Storage: {
     runWithContext: runWithContextMock
@@ -108,12 +118,15 @@ describe( 'ActivityExecutionInterceptor', () => {
     expect( addEventErrorMock ).not.toHaveBeenCalled();
     expect( runWithContextMock ).toHaveBeenCalledWith(
       expect.any( Function ),
-      {
+      expect.objectContaining( {
         parentId: 'act-1',
+        parentName: 'myWorkflow#myStep',
         executionContext: { workflowId: 'wf-1' },
-        workflowFilename: '/workflows/myWorkflow.js'
-      }
+        workflowFilename: '/workflows/myWorkflow.js',
+        workflowHandle: workflowHandleMock
+      } )
     );
+    expect( getHandleMock ).toHaveBeenCalledWith( 'wf-1' );
   } );
 
   it( 'records trace error event on failed execution', async () => {

package/src/worker/interceptors.js

@@ -4,7 +4,7 @@ import { ActivityExecutionInterceptor } from './interceptors/activity.js';
 
 const __dirname = dirname( fileURLToPath( import.meta.url ) );
 
-export const initInterceptors = ( { activities, workflows } ) => ( {
+export const initInterceptors = ( { activities, workflows, connection } ) => ( {
   workflowModules: [ join( __dirname, './interceptors/workflow.js' ) ],
-  activityInbound: [ () => new ActivityExecutionInterceptor( { activities, workflows } ) ]
+  activityInbound: [ () => new ActivityExecutionInterceptor( { activities, workflows, connection } ) ]
 } );