@outputai/core 0.10.1-dev.b7b2fbe.0 → 0.10.1-next.1070949.0

package/src/hooks/index.d.ts

@@ -80,114 +80,108 @@ export interface WorkflowDetails {
 }
 
 /**
- * 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.
+ * Common hook payload fields
  */
 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.
+ * A serialized error-like object emitted from a workflow.
+ *
+ * Additional enumerable properties from the original error may also be present.
  */
-export interface ActivityPayloadBase extends HookPayloadBase {
-  /** Temporal's activityInfo(). */
-  activityInfo: Info;
-  /** Output component kind for the activity, e.g. step or evaluator. */
-  outputActivityKind: string;
+export interface SerializedError {
+  /** Error name. */
+  name: string;
+  /** Error message. */
+  message: string;
+  /** Serialized underlying cause, when present. */
+  cause?: SerializedError;
+  /** Additional properties captured from the original error. */
+  [property: string]: unknown;
 }
 
 /**
- * Payload passed to the onError() handler when a workflow, activity or runtime error occurs.
+ * Common hook payload fields for events associated with an workflow.
  */
-export interface ErrorHookPayload {
-  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
-  eventId: string;
-  /** Timestamp of the event */
-  eventDate: number;
-  /** Origin of the error: workflow execution, activity execution, or runtime. */
-  source: 'workflow' | 'activity' | 'runtime';
+export interface WorkflowPayloadBase extends HookPayloadBase {
   /** Information about the current workflow execution */
-  workflowDetails?: WorkflowDetails;
-  /** Temporal's activityInfo(). If source is activity */
-  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;
+  workflowDetails: WorkflowDetails;
 }
 
 /**
  * Payload passed to the onWorkflowStart() handler when a workflow run begins.
  */
-export type WorkflowStartHookPayload = HookPayloadBase;
+export type WorkflowStartHookPayload = WorkflowPayloadBase;
 
 /**
  * Payload passed to the onWorkflowEnd() handler when a workflow run completes successfully.
  */
-export type WorkflowEndHookPayload = HookPayloadBase;
+export type WorkflowEndHookPayload = WorkflowPayloadBase;
 
 /**
  * Payload passed to the onWorkflowError() handler when a workflow run fails.
  */
-export interface WorkflowErrorHookPayload extends HookPayloadBase {
-  /** The error thrown. */
-  error: Error;
+export interface WorkflowErrorHookPayload extends WorkflowPayloadBase {
+  /** Serialized workflow error. */
+  error: SerializedError;
 }
 
 /**
- * Common activity lifecycle hook payload fields.
+ * Common hook payload fields for events associated with an activity.
  */
-export type ActivityHookPayload = ActivityPayloadBase;
+export interface ActivityPayloadBase extends HookPayloadBase {
+  /** Information about the current workflow execution */
+  workflowDetails: WorkflowDetails;
+  /** Temporal's activityInfo(). */
+  activityInfo: Info;
+  /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
+  outputActivityKind: string;
+}
 
 /**
  * Payload passed to the onActivityStart() handler when an activity starts.
  */
-export type ActivityStartHookPayload = ActivityHookPayload;
+export type ActivityStartHookPayload = ActivityPayloadBase;
 
 /**
  * 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;
-}
+export type ActivityEndHookPayload = ActivityPayloadBase;
 
 /**
  * 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;
+export interface ActivityErrorHookPayload extends ActivityPayloadBase {
   /** The error thrown. */
   error: Error;
 }
 
+/**
+ * Payload passed to the onError() handler when a workflow, activity or runtime error occurs.
+ */
+export type ErrorHookPayload =
+  ( WorkflowPayloadBase & {
+    /** Workflow error origin. */
+    source: 'workflow';
+    /** Serialized workflow error. */
+    error: SerializedError;
+  } ) |
+  ( ActivityErrorHookPayload & {
+    /** Activity error origin. */
+    source: 'activity';
+  } ) |
+  ( HookPayloadBase & {
+    /** Worker runtime error origin. */
+    source: 'runtime';
+    /** The original error instance. */
+    error: Error;
+  } );
+
 /**
  * Register a handler to be invoked on workflow, activity or runtime errors.
  *
@@ -233,8 +227,6 @@ export declare function onWorkflowError( handler: ( payload: WorkflowErrorHookPa
 /**
  * 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;
@@ -242,8 +234,6 @@ export declare function onActivityStart( handler: ( payload: ActivityStartHookPa
 /**
  * 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;
@@ -251,24 +241,32 @@ export declare function onActivityEnd( handler: ( payload: ActivityEndHookPayloa
 /**
  * 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 extends HookPayloadBase {
-  /** Temporal's activityInfo(). */
-  activityInfo: Info;
-  /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
+/** Framework metadata, optional activity context, and the emitted payload. */
+export type ExternalHookPayload<TPayload = unknown> = HookPayloadBase & {
+  /** Information about the current workflow execution, when emitted from an activity. */
+  workflowDetails?: WorkflowDetails;
+  /** Temporal's activityInfo(), when emitted from an activity. */
+  activityInfo?: Info;
+  /** Output component kind, when emitted from an activity. */
   outputActivityKind?: string;
-}
+  /** The emitted payload */
+  payload: TPayload | undefined;
+};
 
-export type OnHookPayload<TAttributes extends Record<string, unknown> = Record<string, unknown>> =
-  OnHookEnvelope & TAttributes;
+/**
+ * Emit a custom event from the current activity.
+ *
+ * @param eventName - The name of the event to emit.
+ * @param payload - Optional value forwarded to on() handlers.
+ */
+export declare function emit(
+  eventName: string,
+  payload?: unknown
+): boolean;
 
 /**
  * Register a handler to be invoked when a given event happens
@@ -276,7 +274,7 @@ export type OnHookPayload<TAttributes extends Record<string, unknown> = Record<s
  * @param eventName - The name of the event to subscribe
  * @param handler - Function called with the event payload
  */
-export declare function on<TAttributes extends Record<string, unknown> = Record<string, unknown>>(
+export declare function on<TPayload = unknown>(
   eventName: string,
-  handler: ( payload: OnHookPayload<TAttributes> ) => void
+  handler: ( event: ExternalHookPayload<TPayload> ) => void
 ): void;

package/src/hooks/index.js

@@ -1,68 +1,76 @@
-import { messageBus } from '#bus';
-import { BusEventType, ComponentType, WORKFLOW_CATALOG } from '#consts';
+import { mainEventBus, stepEventBus } from '#bus';
+import { BusEventType } from '#consts';
+import { serializeError } from '#helpers/error_serializer';
 import { createChildLogger } from '#logger';
+import { pendingHooks } from './pending_hooks.js';
 
 const log = createChildLogger( 'Hooks' );
 
 /**
- * Invokes an external hook handler function with a try catch around it
+ * Invokes a function within a try catch and log the error.
  *
  * @param {Function} fn
  * @param {any} args - Args to invoke the function with
  * @param {string} hookName - hookName to identify this hook function in the logs
  */
-const safeInvoke = async ( fn, args, hookName ) => {
-  try {
-    await fn( args );
-  } catch ( error ) {
-    log.error( `${hookName} hook error`, { message: error.message, stack: error.stack } );
-  }
+const callHookCb = ( fn, args, hookName ) => {
+  const promise = Promise.resolve()
+    .then( () => fn( args ) )
+    .catch( e => log.error( `${hookName} hook error`, { error: serializeError( e ) } ) )
+    .finally( () => pendingHooks.delete( promise ) );
+  pendingHooks.add( promise );
+  return promise;
 };
 
-/** Triggers on any errors: workflow, activity and runtime */
-export const onError = handler => {
-  messageBus.on( BusEventType.ACTIVITY_ERROR, async payload =>
-    safeInvoke( handler, { source: 'activity', ...payload }, 'onError' ) );
-  messageBus.on( BusEventType.WORKFLOW_ERROR, async payload =>
-    safeInvoke( handler, { source: 'workflow', ...payload }, 'onError' ) );
-  messageBus.on( BusEventType.RUNTIME_ERROR, async payload =>
-    safeInvoke( handler, { source: 'runtime', ...payload }, 'onError' ) );
+// General Life-cycle
+// --------------------------------------
+const onError = cb => {
+  mainEventBus.on( BusEventType.ACTIVITY_ERROR, async payload =>
+    callHookCb( cb, { source: 'activity', ...payload }, 'onError' ) );
+  mainEventBus.on( BusEventType.WORKFLOW_ERROR, async payload =>
+    callHookCb( cb, { source: 'workflow', ...payload }, 'onError' ) );
+  mainEventBus.on( BusEventType.RUNTIME_ERROR, async payload =>
+    callHookCb( cb, { source: 'runtime', ...payload }, 'onError' ) );
 };
 
-/** Listen to worker before start events */
-export const onBeforeWorkerStart = handler => messageBus.on( BusEventType.WORKER_BEFORE_START, () =>
-  safeInvoke( handler, undefined, 'onBeforeWorkerStart' ) );
+const onBeforeWorkerStart = cb => mainEventBus.on( BusEventType.WORKER_BEFORE_START, () => callHookCb( cb, undefined, 'onBeforeWorkerStart' ) );
 
-/** Catalog workflow events should not be emitted */
-const shouldEmitWorkflowEvent = workflowDetails => WORKFLOW_CATALOG !== workflowDetails.workflowType;
+// Workflow Life-cycle
+// --------------------------------------
+const onWorkflowStart = cb => mainEventBus.on( BusEventType.WORKFLOW_START, payload => callHookCb( cb, payload, 'onWorkflowStart' ) );
+const onWorkflowEnd = cb => mainEventBus.on( BusEventType.WORKFLOW_END, payload => callHookCb( cb, payload, 'onWorkflowEnd' ) );
+const onWorkflowError = cb => mainEventBus.on( BusEventType.WORKFLOW_ERROR, payload => callHookCb( cb, payload, 'onWorkflowError' ) );
 
-/** Listen to workflow start events, excludes catalog workflow */
-export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowStart' ) : null );
+// Activity Life-cycle
+// --------------------------------------
+const onActivityStart = cb => mainEventBus.on( BusEventType.ACTIVITY_START, fields => callHookCb( cb, fields, 'onActivityStart' ) );
+const onActivityEnd = cb => mainEventBus.on( BusEventType.ACTIVITY_END, fields => callHookCb( cb, fields, 'onActivityEnd' ) );
+const onActivityError = cb => mainEventBus.on( BusEventType.ACTIVITY_ERROR, fields => callHookCb( cb, fields, 'onActivityError' ) );
 
-/** Listen to workflow end events, excludes catalog workflow */
-export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowEnd' ) : null );
-
-/** Listen to workflow error events, excludes catalog workflow */
-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 );
+// Generic Events
+// --------------------------------------
+/** Listen to both sdk and custom events */
+const on = ( eventName, cb ) => {
+  stepEventBus.on( `sdk:${eventName}`, payload => callHookCb( cb, payload, eventName ) );
+  stepEventBus.on( `usr:${eventName}`, payload => callHookCb( cb, payload, eventName ) );
+};
 
-/** 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 );
+/**
+ * Emits a custom event
+ * @param {string} eventName
+ * @param {any} payload
+ */
+const emit = ( eventName, payload ) => stepEventBus.emit( `usr:${eventName}`, payload );
 
-/** Generic listener for events emitted elsewhere (outside core) */
-export const on = ( eventName, handler ) => messageBus.on( `external:${eventName}`, payload =>
-  safeInvoke( handler, payload, eventName ) );
+export {
+  emit,
+  on,
+  onActivityEnd,
+  onActivityError,
+  onActivityStart,
+  onBeforeWorkerStart,
+  onError,
+  onWorkflowEnd,
+  onWorkflowError,
+  onWorkflowStart
+};