@outputai/core 0.5.2 → 0.5.3-next.69060d7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.5.2",
+  "version": "0.5.3-next.69060d7.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -66,6 +66,7 @@
     "#errors": "./src/errors.js",
     "#logger": "./src/logger.js",
     "#utils": "./src/utils/index.js",
+    "#internal_utils/*": "./src/internal_utils/*.js",
     "#tracing": "./src/tracing/internal_interface.js",
     "#trace_attribute": "./src/tracing/trace_attribute.js",
     "#async_storage": "./src/async_storage.js",

package/src/consts.js

@@ -1,10 +1,12 @@
 export const ACTIVITY_GET_TRACE_DESTINATIONS = '__internal#getTraceDestinations';
 export const ACTIVITY_OPTIONS_FILENAME = '__activity_options.js';
 export const ACTIVITY_SEND_HTTP_REQUEST = '__internal#sendHttpRequest';
+export const ACTIVITY_WRAPPER_VERSION_FIELD = '__output_activity_wrapper_version';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const SHARED_STEP_PREFIX = '$shared';
 export const WORKFLOW_CATALOG = '$catalog';
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
+export const WORKFLOW_WRAPPER_VERSION_FIELD = '__output_workflow_wrapper_version';
 
 export const ComponentType = {
   EVALUATOR: 'evaluator',
@@ -34,7 +36,7 @@ export const BusEventType = {
 };
 
 export const Signal = {
-  ADD_ATTRIBUTE: 'add_attribute'
+  SEND_AGGREGATIONS: 'send_aggregations'
 };
 
 export const WorkflowSpecialOutput = {

package/src/interface/workflow.js

@@ -3,11 +3,19 @@ import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4,
 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, Signal } from '#consts';
+import {
+  ACTIVITY_GET_TRACE_DESTINATIONS,
+  ACTIVITY_WRAPPER_VERSION_FIELD,
+  METADATA_ACCESS_SYMBOL,
+  SHARED_STEP_PREFIX,
+  Signal,
+  WORKFLOW_WRAPPER_VERSION_FIELD
+} from '#consts';
 import { deepMerge, setMetadata, toUrlSafeBase64 } from '#utils';
 import { FatalError, ValidationError } from '#errors';
 import { Context } from './workflow_context.js';
-import { aggregateAttributes } from './aggregations.js';
+import { aggregateAttributes, mergeAggregations } from '#internal_utils/aggregations';
+import { extractErrorDetail } from '#internal_utils/errors';
 
 const defaultOptions = {
   activityOptions: {
@@ -24,8 +32,10 @@ const defaultOptions = {
   disableTrace: false
 };
 
-export const extractErrorDetail = ( e, key ) =>
-  e ? ( e.details?.find?.( d => d[key] )?.[key] ?? extractErrorDetail( e.cause, key ) ) : null;
+/**
+ * Checks if the activity result uses the internal wrapper
+ */
+const isActivityResultWrapped = result => result?.[ACTIVITY_WRAPPER_VERSION_FIELD] > 0;
 
 export function workflow( { name, description, inputSchema, outputSchema, fn, options = {}, aliases = [] } ) {
   validateWorkflow( { name, description, inputSchema, outputSchema, fn, options, aliases } );
@@ -56,7 +66,6 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
     }
 
     const { workflowId, runId, memo, startTime } = workflowInfo();
-
     const context = Context.build( { workflowId, runId, continueAsNew, isContinueAsNewSuggested: () => workflowInfo().continueAsNewSuggested } );
 
     // Root workflows will not have the execution context yet, since it is set here.
@@ -78,32 +87,82 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
       activityOptions: memo.activityOptions ?? activityOptions // Also preserve the original activity options
     } );
 
-    // 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;
+    /**
+     * Run the internal activity to retrieve the workflow trace destinations
+     * This only happens at the root workflow because nested share the same trace file
+     * @IMPORTANT Keep support for deprecated non-wrapped activity result to allow for Temporal replays.
+     * @TODO [OUT-468]
+    */
+    const getTraceDestinations = async () => {
+      const result = await steps[ACTIVITY_GET_TRACE_DESTINATIONS]( executionContext );
+      return isActivityResultWrapped( result ) ? result.output : result;
+    };
+
+    // Creates the result wrapper with information about the workflow
+    const workflowResult = {
+      [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
+      aggregations: null,
+      ...( isRoot && {
+        trace: {
+          destinations: await getTraceDestinations()
+        }
+      } )
+    };
+
+    // Combine aggregations in the workflow result aggregations, mutating it
+    const mergeAggregationsInWorkflowResult = aggregations => {
+      workflowResult.aggregations = mergeAggregations( workflowResult.aggregations, aggregations );
+    };
 
-    const attributes = [];
-    setHandler( defineSignal( Signal.ADD_ATTRIBUTE ), e => attributes.push( e ) );
+    setHandler( defineSignal( Signal.SEND_AGGREGATIONS ), aggregations => {
+      mergeAggregationsInWorkflowResult( aggregations );
+    } );
+
+    /**
+     * @IMPORTANT Keep support for deprecated add_attribute Signal to allow for Temporal replays.
+     * @TODO This can be removed 30days after this release
+     */
+    setHandler( defineSignal( 'add_attribute' ), attribute => {
+      mergeAggregationsInWorkflowResult( aggregateAttributes( [ attribute ] ) );
+    } );
+
+    /**
+     * Invoke a step and unwraps the result to extract and merge "aggregations" and return only the output.
+     *
+     * @IMPORTANT Keep support for deprecated non-wrapped activity result to allow for Temporal replays.
+     * @TODO [OUT-468]
+     * @param {Function} step
+     * @param  {...any} args
+     * @returns {any} The step "output"
+     */
+    const callStepAndUnwrapResult = async ( step, ...args ) => {
+      const result = await step( ...args );
+      if ( !isActivityResultWrapped( result ) ) {
+        return result;
+      }
+      const { output, aggregations } = result;
+      if ( aggregations ) {
+        mergeAggregationsInWorkflowResult( aggregations );
+      }
+      return output;
+    };
 
     try {
       // validation comes after setting memo to have that info already set for interceptor even if validations fail
       validateWithSchema( inputSchema, input, `Workflow ${name} input` );
 
       const dispatchers = {
-        invokeStep: async ( stepName, input, options ) => steps[`${name}#${stepName}`]( input, options ),
-        invokeSharedStep: async ( stepName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${stepName}`]( input, options ),
-        invokeEvaluator: async ( evaluatorName, input, options ) => steps[`${name}#${evaluatorName}`]( input, options ),
-        invokeSharedEvaluator: async ( evaluatorName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${evaluatorName}`]( input, options ),
-
-        /**
-         * Start a child workflow
-         *
-         * @param {string} childName
-         * @param {unknown} input
-         * @param {object} extra
-         * @param {boolean} extra.detached
-         * @param {import('@temporalio/workflow').ActivityOptions} extra.options
-         * @returns {Promise<unknown>}
-         */
+        /* This are shortcuts to invoke activities as steps/evaluators both shared and non shared */
+        invokeStep: async ( stepName, input, options ) =>
+          callStepAndUnwrapResult( steps[`${name}#${stepName}`], input, options ),
+        invokeSharedStep: async ( stepName, input, options ) =>
+          callStepAndUnwrapResult( steps[`${SHARED_STEP_PREFIX}#${stepName}`], input, options ),
+        invokeEvaluator: async ( evaluatorName, input, options ) =>
+          callStepAndUnwrapResult( steps[`${name}#${evaluatorName}`], input, options ),
+        invokeSharedEvaluator: async ( evaluatorName, input, options ) =>
+          callStepAndUnwrapResult( steps[`${SHARED_STEP_PREFIX}#${evaluatorName}`], input, options ),
+
+        // Start a new child workflow
         startWorkflow: async ( childName, input, extra = {} ) => {
           try {
             const result = await executeChild( childName, {
@@ -116,33 +175,43 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
                 ...( extra?.options?.activityOptions && { activityOptions: deepMerge( activityOptions, extra.options.activityOptions ) } )
               }
             } );
-            attributes.push( ...( result.attributes ?? [] ) );
+            /**
+             * @IMPORTANT Keep support for deprecated ".attributes" from workflow results to allow for Temporal replays.
+             * @TODO [OUT-468]
+             */
+            if ( result?.attributes ) {
+              mergeAggregationsInWorkflowResult( aggregateAttributes( result.attributes ) );
+            }
+            if ( result?.aggregations ) {
+              mergeAggregationsInWorkflowResult( result.aggregations );
+            }
             return result.output;
           } catch ( error ) {
-            attributes.push( ...( extractErrorDetail( error, 'attributes' ) ?? [] ) );
+            /**
+             * @IMPORTANT Keep support for deprecated ".attributes" from workflow errors to allow for Temporal replays.
+             * @TODO [OUT-468]
+             */
+            const attributesFromError = extractErrorDetail( error, 'attributes' );
+            if ( attributesFromError ) {
+              mergeAggregationsInWorkflowResult( aggregateAttributes( attributesFromError ) );
+            }
+            const aggregationsFromError = extractErrorDetail( error, 'aggregations' );
+            if ( aggregationsFromError ) {
+              mergeAggregationsInWorkflowResult( aggregationsFromError );
+            }
             throw error;
           }
         }
       };
 
-      const output = await fn.call( dispatchers, input, context );
+      workflowResult.output = await fn.call( dispatchers, input, context );
 
-      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
-
-      if ( isRoot ) {
-        // Append the trace info to the result of the workflow
-        return { output, trace: { destinations: traceDestinations }, attributes, aggregations: aggregateAttributes( attributes ) };
-      }
+      validateWithSchema( outputSchema, workflowResult.output, `Workflow ${name} output` );
 
-      return { output, attributes };
+      return workflowResult;
     } catch ( e ) {
-      // 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].trace = { destinations: traceDestinations };
-        e[METADATA_ACCESS_SYMBOL].aggregations = aggregateAttributes( attributes );
-      }
+      // Append the result as metadata of the error, so it can be read by the interceptor.
+      e[METADATA_ACCESS_SYMBOL] = { ...( e[METADATA_ACCESS_SYMBOL] ?? {} ), ...workflowResult };
       throw e;
     }
   };

package/src/interface/workflow.replay_compatibility.spec.js

@@ -0,0 +1,254 @@
+import { ACTIVITY_GET_TRACE_DESTINATIONS, METADATA_ACCESS_SYMBOL, WORKFLOW_WRAPPER_VERSION_FIELD } 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 );
+
+const createStepsProxy = ( stepSpy = vi.fn() ) =>
+  new Proxy( {}, {
+    get: ( _, prop ) => {
+      if ( prop === ACTIVITY_GET_TRACE_DESTINATIONS ) {
+        return traceDestinationsStepMock;
+      }
+      if ( typeof prop === 'string' && prop.includes( '#' ) ) {
+        return stepSpy;
+      }
+      return vi.fn();
+    }
+  } );
+
+const proxyActivitiesMock = vi.fn( () => createStepsProxy() );
+
+const workflowInfoReturn = {
+  workflowId: 'wf-test-123',
+  workflowType: 'test_wf',
+  memo: {},
+  startTime: new Date( '2025-01-01T00:00:00Z' ),
+  continueAsNewSuggested: false
+};
+const workflowInfoMock = vi.fn( () => ( { ...workflowInfoReturn } ) );
+
+vi.mock( '@temporalio/workflow', () => ( {
+  proxyActivities: ( ...args ) => proxyActivitiesMock( ...args ),
+  inWorkflowContext: inWorkflowContextMock,
+  executeChild: ( ...args ) => executeChildMock( ...args ),
+  workflowInfo: workflowInfoMock,
+  uuid4: () => '550e8400e29b41d4a716446655440000',
+  ParentClosePolicy: { TERMINATE: 'TERMINATE', ABANDON: 'ABANDON' },
+  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 => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    SHARED_STEP_PREFIX: '__shared',
+    ACTIVITY_GET_TRACE_DESTINATIONS: '__internal#getTraceDestinations'
+  };
+} );
+
+describe( 'workflow() replay compatibility', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    inWorkflowContextMock.mockReturnValue( true );
+    defineSignalMock.mockImplementation( name => name );
+    workflowInfoReturn.memo = {};
+    workflowInfoMock.mockReturnValue( { ...workflowInfoReturn } );
+    proxyActivitiesMock.mockImplementation( () => createStepsProxy() );
+    traceDestinationsStepMock.mockResolvedValue( { local: '/tmp/trace' } );
+  } );
+
+  it( 'preserves old plain trace destination activity results', async () => {
+    const { workflow } = await import( './workflow.js' );
+
+    const wf = workflow( {
+      name: 'root_wf',
+      description: 'Root',
+      inputSchema: z.object( {} ),
+      outputSchema: z.object( { v: z.number() } ),
+      fn: async () => ( { v: 42 } )
+    } );
+
+    const result = await wf( {} );
+    expect( result ).toEqual( {
+      [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
+      output: { v: 42 },
+      trace: { destinations: { local: '/tmp/trace' } },
+      aggregations: null
+    } );
+  } );
+
+  it( 'converts old add_attribute signals into aggregations', async () => {
+    const { workflow } = await import( './workflow.js' );
+    const { Attribute } = await import( '#trace_attribute' );
+    const handlers = { addAttribute: () => {} };
+    setHandlerMock.mockImplementation( ( signalName, handler ) => {
+      if ( signalName === '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 ).not.toHaveProperty( 'attributes' );
+    expect( result.aggregations ).toEqual( {
+      cost: { total: 2.75 },
+      tokens: {
+        total: 25_000,
+        input: 20_000,
+        output: 5_000
+      },
+      httpRequests: { total: 1 }
+    } );
+  } );
+
+  it( 'preserves old plain activity results from steps', async () => {
+    const stepSpy = vi.fn().mockResolvedValue( { legacy: true } );
+    proxyActivitiesMock.mockImplementation( () => createStepsProxy( stepSpy ) );
+    const { workflow } = await import( './workflow.js' );
+
+    const wf = workflow( {
+      name: 'legacy_step_wf',
+      description: 'Legacy step result',
+      inputSchema: z.object( {} ),
+      outputSchema: z.object( { legacy: z.boolean() } ),
+      async fn() {
+        return this.invokeStep( 'myStep', { foo: 1 } );
+      }
+    } );
+
+    const result = await wf( {} );
+    expect( result.output ).toEqual( { legacy: true } );
+    expect( result.aggregations ).toEqual( null );
+  } );
+
+  it( 'converts old child workflow attributes into parent aggregations', 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( {
+      [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
+      output: { child: 'ok' },
+      trace: { destinations: { local: '/tmp/trace' } },
+      aggregations: {
+        cost: { total: 0.4 },
+        tokens: {
+          total: 20,
+          input: 20
+        },
+        httpRequests: { total: 0 }
+      }
+    } );
+  } );
+
+  it( 'converts old child workflow error attributes into parent error metadata aggregations', async () => {
+    const { workflow } = await import( './workflow.js' );
+    const { ChildWorkflowFailure } = await import( '@temporalio/workflow' );
+    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( {
+      [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
+      trace: { destinations: { local: '/tmp/trace' } },
+      aggregations: {
+        cost: { total: 2 },
+        tokens: { total: 0 },
+        httpRequests: { total: 0 }
+      }
+    } );
+  } );
+} );