@outputai/core 0.8.2-next.89b6f8c.0 → 0.8.2-next.aaa08cc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.8.2-next.89b6f8c.0",
+  "version": "0.8.2-next.aaa08cc.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/hooks/index.d.ts

@@ -79,6 +79,47 @@ export interface WorkflowDetails {
   attempt: number;
 }
 
+/**
+ * Attribute totals collected while an activity executes.
+ */
+export interface Aggregations {
+  /** Cost totals collected from HTTP request cost and LLM usage attributes. */
+  cost: {
+    total: number;
+  };
+  /** Token totals collected from LLM usage attributes. */
+  tokens: {
+    [tokenType: string]: number | undefined;
+    total: number;
+  };
+  /** HTTP request count totals. */
+  httpRequests: {
+    total: number;
+  };
+}
+
+/**
+ * Common lifecycle hook payload fields for events associated with a workflow.
+ */
+export interface HookPayloadBase {
+  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
+  eventId: string;
+  /** Timestamp of the event */
+  eventDate: number;
+  /** Information about the current workflow execution */
+  workflowDetails: WorkflowDetails;
+}
+
+/**
+ * Common hook payload fields for events associated with an activity.
+ */
+export interface ActivityPayloadBase extends HookPayloadBase {
+  /** Temporal's activityInfo(). */
+  activityInfo: Info;
+  /** Output component kind for the activity, e.g. step or evaluator. */
+  outputActivityKind: string;
+}
+
 /**
  * Payload passed to the onError() handler when a workflow, activity or runtime error occurs.
  */
@@ -95,6 +136,8 @@ export interface ErrorHookPayload {
   activityInfo?: Info;
   /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
   outputActivityKind?: string;
+  /** Attribute totals collected during the activity execution. */
+  aggregations?: Aggregations | null;
   /** The error thrown. */
   error: Error;
 }
@@ -102,37 +145,45 @@ export interface ErrorHookPayload {
 /**
  * Payload passed to the onWorkflowStart() handler when a workflow run begins.
  */
-export interface WorkflowStartHookPayload {
-  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
-  eventId: string;
-  /** Timestamp of the event */
-  eventDate: number;
-  /** Information about the current workflow execution */
-  workflowDetails: WorkflowDetails;
-}
+export type WorkflowStartHookPayload = HookPayloadBase;
 
 /**
  * Payload passed to the onWorkflowEnd() handler when a workflow run completes successfully.
  */
-export interface WorkflowEndHookPayload {
-  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
-  eventId: string;
-  /** Timestamp of the event */
-  eventDate: number;
-  /** Information about the current workflow execution */
-  workflowDetails: WorkflowDetails;
-}
+export type WorkflowEndHookPayload = HookPayloadBase;
 
 /**
  * Payload passed to the onWorkflowError() handler when a workflow run fails.
  */
-export interface WorkflowErrorHookPayload {
-  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
-  eventId: string;
-  /** Timestamp of the event */
-  eventDate: number;
-  /** Information about the current workflow execution */
-  workflowDetails: WorkflowDetails;
+export interface WorkflowErrorHookPayload extends HookPayloadBase {
+  /** The error thrown. */
+  error: Error;
+}
+
+/**
+ * Common activity lifecycle hook payload fields.
+ */
+export type ActivityHookPayload = ActivityPayloadBase;
+
+/**
+ * Payload passed to the onActivityStart() handler when an activity starts.
+ */
+export type ActivityStartHookPayload = ActivityHookPayload;
+
+/**
+ * Payload passed to the onActivityEnd() handler when an activity completes successfully.
+ */
+export interface ActivityEndHookPayload extends ActivityHookPayload {
+  /** Attribute totals collected during the activity execution. */
+  aggregations: Aggregations | null;
+}
+
+/**
+ * Payload passed to the onActivityError() handler when an activity fails.
+ */
+export interface ActivityErrorHookPayload extends ActivityHookPayload {
+  /** Attribute totals collected during the activity execution. */
+  aggregations: Aggregations | null;
   /** The error thrown. */
   error: Error;
 }
@@ -179,16 +230,37 @@ export declare function onWorkflowEnd( handler: ( payload: WorkflowEndHookPayloa
  */
 export declare function onWorkflowError( handler: ( payload: WorkflowErrorHookPayload ) => void ): void;
 
+/**
+ * Register a handler to be invoked when an activity starts.
+ *
+ * Excludes internal activities.
+ *
+ * @param handler - Function called with the activity start payload.
+ */
+export declare function onActivityStart( handler: ( payload: ActivityStartHookPayload ) => void ): void;
+
+/**
+ * Register a handler to be invoked when an activity completes successfully.
+ *
+ * Excludes internal activities.
+ *
+ * @param handler - Function called with the activity end payload.
+ */
+export declare function onActivityEnd( handler: ( payload: ActivityEndHookPayload ) => void ): void;
+
+/**
+ * Register a handler to be invoked when an activity fails.
+ *
+ * Excludes internal activities.
+ *
+ * @param handler - Function called with the activity error payload.
+ */
+export declare function onActivityError( handler: ( payload: ActivityErrorHookPayload ) => void ): void;
+
 /**
  * Framework-managed envelope added to payloads passed to on() handlers.
  */
-export interface OnHookEnvelope {
-  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
-  eventId: string;
-  /** Timestamp of the event */
-  eventDate: number;
-  /** Information about the current workflow execution */
-  workflowDetails: WorkflowDetails;
+export interface OnHookEnvelope extends HookPayloadBase {
   /** Temporal's activityInfo(). */
   activityInfo: Info;
   /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */

package/src/hooks/index.js

@@ -1,5 +1,5 @@
 import { messageBus } from '#bus';
-import { BusEventType, WORKFLOW_CATALOG } from '#consts';
+import { BusEventType, ComponentType, WORKFLOW_CATALOG } from '#consts';
 import { createChildLogger } from '#logger';
 
 const log = createChildLogger( 'Hooks' );
@@ -48,6 +48,21 @@ export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END
 export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { workflowDetails, ...eventFields } ) =>
   shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowError' ) : null );
 
+/** Internal activities do not trigger hooks */
+const shouldEmitActivityEvent = outputActivityKind => outputActivityKind !== ComponentType.INTERNAL_STEP;
+
+/** Listen to workflow start events, excludes catalog workflow */
+export const onActivityStart = handler => messageBus.on( BusEventType.ACTIVITY_START, ( { outputActivityKind, ...eventFields } ) =>
+  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityStart' ) : null );
+
+/** Listen to workflow end events, excludes catalog workflow */
+export const onActivityEnd = handler => messageBus.on( BusEventType.ACTIVITY_END, ( { outputActivityKind, ...eventFields } ) =>
+  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityEnd' ) : null );
+
+/** Listen to workflow error events, excludes catalog workflow */
+export const onActivityError = handler => messageBus.on( BusEventType.ACTIVITY_ERROR, ( { outputActivityKind, ...eventFields } ) =>
+  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityError' ) : null );
+
 /** Generic listener for events emitted elsewhere (outside core) */
 export const on = ( eventName, handler ) => messageBus.on( `external:${eventName}`, payload =>
   safeInvoke( handler, payload, eventName ) );

package/src/hooks/index.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { BusEventType, WORKFLOW_CATALOG } from '#consts';
+import { BusEventType, ComponentType, WORKFLOW_CATALOG } from '#consts';
 
 const logErrorMock = vi.hoisted( () => vi.fn() );
 const createChildLoggerMock = vi.hoisted( () =>
@@ -18,6 +18,9 @@ vi.mock( '#bus', () => ( { messageBus: messageBusMock } ) );
 
 import {
   on,
+  onActivityEnd,
+  onActivityError,
+  onActivityStart,
   onBeforeWorkerStart,
   onError,
   onWorkflowEnd,
@@ -49,6 +52,12 @@ const activityInfo = {
 
 const eventDate = 1710000001234;
 
+const aggregations = {
+  cost: { total: 0 },
+  tokens: { total: 0 },
+  httpRequests: { total: 1 }
+};
+
 describe( 'hooks/index', () => {
   beforeEach( () => {
     vi.clearAllMocks();
@@ -198,6 +207,51 @@ describe( 'hooks/index', () => {
     } );
   } );
 
+  describe( 'activity lifecycle hooks', () => {
+    const cases = [
+      [ 'onActivityStart', onActivityStart, BusEventType.ACTIVITY_START, undefined ],
+      [ 'onActivityEnd', onActivityEnd, BusEventType.ACTIVITY_END, { aggregations } ],
+      [ 'onActivityError', onActivityError, BusEventType.ACTIVITY_ERROR, { error: new Error( 'activity failed' ) } ]
+    ];
+
+    it.each( cases )( '%s skips internal activities and forwards bus fields', async ( _name, registerHook, eventType, extraFields = {} ) => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      registerHook( handler );
+
+      expect( messageBusMock.on ).toHaveBeenCalledWith( eventType, expect.any( Function ) );
+
+      await Promise.resolve( onHandlers[eventType]( {
+        eventId: 'evt-ignored',
+        eventDate,
+        activityInfo,
+        workflowDetails,
+        outputActivityKind: ComponentType.INTERNAL_STEP,
+        ...extraFields
+      } ) );
+      expect( handler ).not.toHaveBeenCalled();
+
+      await Promise.resolve( onHandlers[eventType]( {
+        eventId: 'evt-activity-1',
+        eventDate,
+        activityInfo,
+        workflowDetails,
+        outputActivityKind: ComponentType.STEP,
+        extra: 'passthrough',
+        ...extraFields
+      } ) );
+
+      expect( handler ).toHaveBeenCalledWith( {
+        eventId: 'evt-activity-1',
+        eventDate,
+        activityInfo,
+        workflowDetails,
+        outputActivityKind: ComponentType.STEP,
+        extra: 'passthrough',
+        ...extraFields
+      } );
+    } );
+  } );
+
   describe( 'on', () => {
     it( 'subscribes to external event channel and forwards payload', async () => {
       const handler = vi.fn().mockResolvedValue( undefined );

package/src/worker/interceptors/activity.js

@@ -77,20 +77,17 @@ export class ActivityExecutionInterceptor {
 
       const output = await Storage.runWithContext( async _ => next( input ), storageContext );
 
-      messageBus.emit( BusEventType.ACTIVITY_END, { activityInfo, workflowDetails, outputActivityKind } );
+      const aggregations = state.attributes.length > 0 ? aggregateAttributes( state.attributes ) : null;
+
+      messageBus.emit( BusEventType.ACTIVITY_END, { activityInfo, aggregations, workflowDetails, outputActivityKind } );
       Tracing.addEventEnd( { id: activityId, details: output, traceInfo } );
 
-      return {
-        [ACTIVITY_WRAPPER_VERSION_FIELD]: 1,
-        output,
-        aggregations: state.attributes.length > 0 ? aggregateAttributes( state.attributes ) : null
-      };
+      return { [ACTIVITY_WRAPPER_VERSION_FIELD]: 1, output, aggregations };
 
     } catch ( error ) {
-      messageBus.emit( BusEventType.ACTIVITY_ERROR, { activityInfo, workflowDetails, outputActivityKind, error } );
-      Tracing.addEventError( { id: activityId, details: error, traceInfo } );
-
       const aggregations = state.attributes.length > 0 ? aggregateAttributes( state.attributes ) : null;
+      messageBus.emit( BusEventType.ACTIVITY_ERROR, { activityInfo, aggregations, workflowDetails, outputActivityKind, error } );
+      Tracing.addEventError( { id: activityId, details: error, traceInfo } );
 
       throw aggregations ? buildApplicationFailureWithDetails( error, { aggregations } ) : error;
     } finally {

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

@@ -100,6 +100,12 @@ const httpRequestAttribute = {
   requestId: 'req-1'
 };
 
+const httpRequestAggregations = {
+  cost: { total: 0 },
+  tokens: { total: 0 },
+  httpRequests: { total: 1 }
+};
+
 describe( 'ActivityExecutionInterceptor', () => {
   beforeEach( () => {
     vi.clearAllMocks();
@@ -136,7 +142,7 @@ describe( 'ActivityExecutionInterceptor', () => {
     );
     expect( messageBusEmitMock ).toHaveBeenCalledWith(
       BusEventType.ACTIVITY_END,
-      { activityInfo: activityInfoMock, workflowDetails: workflowDetailsMock, outputActivityKind: 'step' }
+      { activityInfo: activityInfoMock, aggregations: null, workflowDetails: workflowDetailsMock, outputActivityKind: 'step' }
     );
     expect( addEventStartMock ).toHaveBeenCalledWith( {
       id: 'act-1',
@@ -189,14 +195,16 @@ describe( 'ActivityExecutionInterceptor', () => {
 
     await expect( interceptor.execute( makeInput(), next ) ).resolves.toEqual( {
       output: { result: 'ok' },
-      aggregations: {
-        cost: { total: 0 },
-        tokens: { total: 0 },
-        httpRequests: { total: 1 }
-      },
+      aggregations: httpRequestAggregations,
       [ACTIVITY_WRAPPER_VERSION_FIELD]: 1
     } );
 
+    expect( messageBusEmitMock ).toHaveBeenCalledWith( BusEventType.ACTIVITY_END, {
+      activityInfo: activityInfoMock,
+      aggregations: httpRequestAggregations,
+      workflowDetails: workflowDetailsMock,
+      outputActivityKind: 'step'
+    } );
   } );
 
   it( 'stores collected aggregations in ApplicationFailure details after failed execution', async () => {
@@ -215,15 +223,17 @@ describe( 'ActivityExecutionInterceptor', () => {
       message: 'step failed',
       type: 'Error',
       details: [ {
-        aggregations: {
-          cost: { total: 0 },
-          tokens: { total: 0 },
-          httpRequests: { total: 1 }
-        }
+        aggregations: httpRequestAggregations
       } ],
       cause: error
     } );
-    expect( messageBusEmitMock ).toHaveBeenCalledWith( BusEventType.ACTIVITY_ERROR, expect.objectContaining( { error } ) );
+    expect( messageBusEmitMock ).toHaveBeenCalledWith( BusEventType.ACTIVITY_ERROR, {
+      activityInfo: activityInfoMock,
+      aggregations: httpRequestAggregations,
+      workflowDetails: workflowDetailsMock,
+      outputActivityKind: 'step',
+      error
+    } );
     expect( addEventErrorMock ).toHaveBeenCalledOnce();
     expect( addEventEndMock ).not.toHaveBeenCalled();
   } );
@@ -243,13 +253,7 @@ describe( 'ActivityExecutionInterceptor', () => {
 
     expect( thrown.details ).toEqual( [
       { domain: { reason: 'bad-input' } },
-      {
-        aggregations: {
-          cost: { total: 0 },
-          tokens: { total: 0 },
-          httpRequests: { total: 1 }
-        }
-      }
+      { aggregations: httpRequestAggregations }
     ] );
   } );
 
@@ -300,13 +304,7 @@ describe( 'ActivityExecutionInterceptor', () => {
       nonRetryable: true,
       details: [
         { domain: { reason: 'bad-input' } },
-        {
-          aggregations: {
-            cost: { total: 0 },
-            tokens: { total: 0 },
-            httpRequests: { total: 1 }
-          }
-        }
+        { aggregations: httpRequestAggregations }
       ]
     } );
   } );
@@ -324,6 +322,7 @@ describe( 'ActivityExecutionInterceptor', () => {
     expect( messageBusEmitMock ).toHaveBeenCalledWith( BusEventType.ACTIVITY_START, expect.any( Object ) );
     expect( messageBusEmitMock ).toHaveBeenCalledWith( BusEventType.ACTIVITY_ERROR, {
       activityInfo: activityInfoMock,
+      aggregations: null,
       workflowDetails: workflowDetailsMock,
       outputActivityKind: 'step',
       error