@outputai/core 0.8.2-next.e1cd79b.0 → 0.8.2-next.e658cc2.0

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/index.d.ts

@@ -2,12 +2,12 @@
  * Export all types from the interface
  *
  */
-export * from './interface/index.d.ts';
+export * from './interface/index.js';
 
 /**
  * Exports all errors
  */
-export * from './errors.d.ts';
+export * from './errors.js';
 
 /**
  * Expose z from Zod as a convenience.

package/src/interface/evaluator.d.ts

@@ -22,7 +22,7 @@ export type EvaluatorOptions = {
  */
 export type EvaluatorFunction<
   InputSchema extends AnyZodSchema | undefined = undefined,
-  Result extends EvaluationResult
+  Result extends EvaluationResult = EvaluationResult
 > = InputSchema extends AnyZodSchema ?
   ( input: z.infer<InputSchema> ) => Promise<Result> :
   () => Promise<Result>;
@@ -34,7 +34,7 @@ export type EvaluatorFunction<
  *
  * It adds input validation based on the `inputSchema`.
  */
-export type EvaluatorFunctionWrapper<EvaluatorFunction> =
+export type EvaluatorFunctionWrapper<EvaluatorFunction extends ( ...args: any ) => any> = // eslint-disable-line @typescript-eslint/no-explicit-any
   Parameters<EvaluatorFunction> extends [infer Input] ?
     ( input: Input ) => ReturnType<EvaluatorFunction> :
     () => ReturnType<EvaluatorFunction>;

package/src/interface/evaluator.js

@@ -1,6 +1,5 @@
 import { EvaluatorValidator } from './validations/index.js';
-import { setMetadata } from '#utils';
-import { ComponentType } from '#consts';
+import { createEvaluator } from '#helpers/component';
 
 /**
  * Create a new evaluator (activity flavor) and return a wrapper function around its fn handler
@@ -9,13 +8,16 @@ export function evaluator( { name, description, inputSchema, fn, options } ) {
   EvaluatorValidator.validateDefinition( { name, description, inputSchema, fn, options } );
   const validator = new EvaluatorValidator( { name, inputSchema } );
 
-  const wrapper = async input => {
-    validator.validateInput( input );
-    const output = await fn( input );
-    validator.validateOutput( output );
-    return output;
-  };
-
-  setMetadata( wrapper, { name, description, inputSchema, type: ComponentType.EVALUATOR, options } );
-  return wrapper;
-};
+  return createEvaluator( {
+    name,
+    description,
+    inputSchema,
+    options,
+    handler: async input => {
+      validator.validateInput( input );
+      const output = await fn( input );
+      validator.validateOutput( output );
+      return output;
+    }
+  } );
+}

package/src/interface/evaluator.spec.js

@@ -7,12 +7,12 @@ import {
   EvaluationFeedback
 } from './evaluation_result.js';
 import { ValidationError } from '#errors';
-import { ComponentType } from '#consts';
 
 const validateDefinitionMock = vi.hoisted( () => vi.fn() );
 const validateInputMock = vi.hoisted( () => vi.fn() );
 const validateOutputMock = vi.hoisted( () => vi.fn() );
 const validatorConstructorMock = vi.hoisted( () => vi.fn() );
+const createEvaluatorMock = vi.hoisted( () => vi.fn( ( { handler } ) => handler ) );
 
 vi.mock( './validations/index.js', () => {
   class EvaluatorValidator {
@@ -30,12 +30,16 @@ vi.mock( './validations/index.js', () => {
   return { EvaluatorValidator };
 } );
 
+vi.mock( '#helpers/component', () => ( {
+  createEvaluator: createEvaluatorMock
+} ) );
+
 describe( 'evaluator()', () => {
   beforeEach( () => {
     vi.clearAllMocks();
   } );
 
-  it( 'validates the definition, creates a runtime validator, and attaches metadata', async () => {
+  it( 'validates the definition, creates a runtime validator, and creates an evaluator component', async () => {
     const { evaluator } = await import( './evaluator.js' );
     const inputSchema = { safeParse: vi.fn() };
     const fn = vi.fn().mockResolvedValue( new EvaluationResult( { value: 'ok', confidence: 1 } ) );
@@ -61,14 +65,14 @@ describe( 'evaluator()', () => {
       inputSchema
     } );
 
-    const [ metadataSymbol ] = Object.getOwnPropertySymbols( wrapper );
-    expect( wrapper[metadataSymbol] ).toEqual( {
+    expect( createEvaluatorMock ).toHaveBeenCalledWith( {
       name: 'test_evaluator',
       description: 'Test evaluator',
       inputSchema,
-      type: ComponentType.EVALUATOR,
-      options
+      options,
+      handler: expect.any( Function )
     } );
+    expect( wrapper ).toBe( createEvaluatorMock.mock.calls[0][0].handler );
   } );
 
   it( 'validates input and output around the evaluator function', async () => {

package/src/interface/index.d.ts

@@ -1,9 +1,10 @@
 /**
  * Exports all public methods from the interface
  */
-export * from './webhook.d.ts';
-export * from './workflow_utils.d.ts';
-export * from './step.d.ts';
-export * from './evaluator.d.ts';
-export * from './workflow.d.ts';
-export * from './evaluation_result.d.ts';
+export * from './webhook.js';
+export * from './workflow_utils.js';
+export * from './step.js';
+export * from './evaluator.js';
+export * from './workflow.js';
+export * from './evaluation_result.js';
+export * from './logger.js';

package/src/interface/index.js

@@ -10,11 +10,13 @@ import { step } from './step.js';
 import { workflow } from './workflow.js';
 import { executeInParallel } from './workflow_utils.js';
 import { sendHttpRequest, sendPostRequestAndAwaitWebhook } from './webhook.js';
+import { Logger } from './logger.js';
 
 export {
   evaluator,
   step,
   workflow,
+  Logger,
   EvaluationNumberResult,
   EvaluationStringResult,
   EvaluationBooleanResult,

package/src/interface/logger.d.ts

@@ -0,0 +1,61 @@
+type Logger = {
+  /**
+   * Log an error (level 0)
+   * @param message Log message
+   * @param metadata Additional information to be displayed
+   */
+  error( message: string, metadata?: Record<string, unknown> ) : void,
+
+  /**
+   * Log a warn (level 1)
+   * @param message Log message
+   * @param metadata Additional information to be displayed
+   */
+  warn( message: string, metadata?: Record<string, unknown> ) : void,
+
+  /**
+   * Log an info (level 2)
+   * @param message Log message
+   * @param metadata Additional information to be displayed
+   */
+  info( message: string, metadata?: Record<string, unknown> ) : void,
+
+  /**
+   * Log http (level 3)
+   * @param message Log message
+   * @param metadata Additional information to be displayed
+   */
+  http( message: string, metadata?: Record<string, unknown> ) : void,
+
+  /**
+   * Log verbose (level 4)
+   * @param message Log message
+   * @param metadata Additional information to be displayed
+   */
+  verbose( message: string, metadata?: Record<string, unknown> ) : void,
+
+  /**
+   * Log debug (level 5)
+   * @param message Log message
+   * @param metadata Additional information to be displayed
+   */
+  debug( message: string, metadata?: Record<string, unknown> ) : void,
+
+  /**
+   * Log silly (level 6)
+   * @param message Log message
+   * @param metadata Additional information to be displayed
+   */
+  silly( message: string, metadata?: Record<string, unknown> ) : void,
+
+  /**
+   * Creates a new Logger with a namespace value preset for all emitted logs.
+   * @param namespace
+   */
+  createLogger( namespace: string ) : Logger
+};
+
+/**
+ * Logger tool. Can be used in activities or workflows. Logs together with the framework's own logs.
+ */
+export declare const Logger : Logger;

package/src/interface/logger.js

@@ -0,0 +1,73 @@
+import { inWorkflowContext } from '@temporalio/workflow';
+import { proxySinks } from '@temporalio/workflow';
+import { ACTIVITY_LOGGER_SYMBOL } from '#consts';
+import { isPlainObject } from '#helpers/object';
+
+const reservedMetadataFields = new Set( [
+  // Winston fields
+  'label',
+  'level',
+  'message',
+  'metadata',
+  'splat',
+  'stack',
+  'timestamp',
+  // reserved fields enriched by us
+  'workflowId',
+  'workflowType',
+  'runId',
+  'activityId',
+  'activityType',
+  'service',
+  'environment'
+] );
+
+// This is inoffensive and can be used outside workflow sandbox
+const sinks = proxySinks();
+
+// Winston uses npm levels by default: https://github.com/winstonjs/winston#logging-levels
+// Convert npm log levels to console levels
+const levelToConsole = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  http: 'log',
+  verbose: 'log',
+  debug: 'debug',
+  silly: 'log'
+};
+const levels = Object.keys( levelToConsole );
+
+/** Drops reserved keys from object */
+const removeReservedFields = obj => Object.fromEntries( Object.entries( obj ).filter( ( [ k ] ) => !reservedMetadataFields.has( k ) ) );
+
+/** Dispatch the log message downstream */
+const log = ( level, namespace, message, metadata ) => {
+  const baseMetadata = namespace ? { namespace } : {};
+  const sanitized = {
+    message: String( message ),
+    metadata: { ...baseMetadata, ...isPlainObject( metadata ) ? removeReservedFields( metadata ) : {} }
+  };
+
+  // When inside workflow, use sinks to send logs out
+  if ( inWorkflowContext() ) {
+    sinks.workflow.log( { level, ...sanitized } );
+  // When inside activities, use the global function to ship logs
+  } else if ( typeof globalThis[ACTIVITY_LOGGER_SYMBOL] === 'function' ) {
+    globalThis[ACTIVITY_LOGGER_SYMBOL]( { level, ...sanitized } );
+  // This fallback is used on unit tests
+  } else {
+    console[levelToConsole[level]]( sanitized.message, sanitized.metadata );
+  }
+};
+
+/** Creates a new logger. It uses the npm levels, and for each level, bind the log function */
+const createLogger = namespace => ( {
+  ...Object.fromEntries( levels.map( l => [ l, log.bind( null, l, namespace ) ] ) ),
+  createLogger
+} );
+
+/** This is the default logger instance */
+const logger = createLogger( null );
+
+export { logger as Logger };