@outputai/core 0.4.1-dev.56c13a8.0 → 0.4.1-dev.6555a2c.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.4.1-dev.56c13a8.0",
+  "version": "0.4.1-dev.6555a2c.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -19,9 +19,6 @@
     "./sdk_utils": {
       "types": "./src/utils/index.d.ts",
       "import": "./src/utils/index.js"
-    },
-    "./sdk_tracing_tools": {
-      "import": "./src/tracing/tools/index.js"
     }
   },
   "files": [
@@ -36,6 +33,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "3.1038.0",
+    "@aws-sdk/lib-storage": "3.1038.0",
     "@babel/generator": "7.29.1",
     "@babel/parser": "7.29.2",
     "@babel/traverse": "7.29.0",
@@ -45,6 +43,8 @@
     "@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",
     "undici": "8.1.0",
@@ -67,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/events.d.ts

@@ -1,5 +1,10 @@
 /**
- * Emits a custom event
+ * Emits a custom event on the in-process message bus.
+ *
+ * The framework automatically attaches `workflowId`, `runId`, and `activityId`
+ * (pulled from `executionContext`) onto every emitted payload, so consumer
+ * subscribers registered via `on(...)` always receive those identifiers
+ * alongside whatever custom fields the emitter supplies.
  *
  * @param eventName - The name of the event to emit
  * @param payload - An optional payload to send to the event

package/src/activity_integration/events.js

@@ -5,6 +5,6 @@ export const emitEvent = ( eventName, payload ) => {
   const ctx = Storage.load();
 
   const { executionContext, parentId: activityId } = ctx ?? {};
-  const { workflowId } = executionContext ?? {};
-  messageBus.emit( `external:${eventName}`, { workflowId, activityId, ...payload ?? {} } );
+  const { workflowId, runId } = executionContext ?? {};
+  messageBus.emit( `external:${eventName}`, { ...payload ?? {}, workflowId, runId, activityId } );
 };

package/src/activity_integration/events.spec.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const loadMock = vi.hoisted( () => vi.fn() );
+const emitMock = vi.hoisted( () => vi.fn() );
+
+vi.mock( '#async_storage', () => ( {
+  Storage: { load: loadMock }
+} ) );
+
+vi.mock( '#bus', () => ( {
+  messageBus: { emit: emitMock }
+} ) );
+
+import { emitEvent } from './events.js';
+
+describe( 'emitEvent', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+  } );
+
+  it( 'forwards workflowId, runId, and activityId from executionContext', () => {
+    loadMock.mockReturnValue( {
+      executionContext: { workflowId: 'wf-1', runId: 'run-1' },
+      parentId: 'act-1'
+    } );
+
+    emitEvent( 'cost:llm:request', { modelId: 'gpt-4o' } );
+
+    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:llm:request', {
+      workflowId: 'wf-1',
+      runId: 'run-1',
+      activityId: 'act-1',
+      modelId: 'gpt-4o'
+    } );
+  } );
+
+  it( 'handles missing executionContext gracefully', () => {
+    loadMock.mockReturnValue( undefined );
+
+    emitEvent( 'foo:bar', { x: 1 } );
+
+    expect( emitMock ).toHaveBeenCalledWith( 'external:foo:bar', {
+      workflowId: undefined,
+      runId: undefined,
+      activityId: undefined,
+      x: 1
+    } );
+  } );
+
+  it( 'handles missing payload', () => {
+    loadMock.mockReturnValue( {
+      executionContext: { workflowId: 'wf-2', runId: 'run-2' },
+      parentId: 'act-2'
+    } );
+
+    emitEvent( 'lifecycle:start' );
+
+    expect( emitMock ).toHaveBeenCalledWith( 'external:lifecycle:start', {
+      workflowId: 'wf-2',
+      runId: 'run-2',
+      activityId: 'act-2'
+    } );
+  } );
+
+  it( 'does not let payload override workflowId / runId / activityId', () => {
+    loadMock.mockReturnValue( {
+      executionContext: { workflowId: 'wf-3', runId: 'run-3' },
+      parentId: 'act-3'
+    } );
+
+    emitEvent( 'cost:http:request', {
+      workflowId: 'should-be-overridden',
+      runId: 'should-be-overridden',
+      activityId: 'should-be-overridden',
+      url: 'https://example.com'
+    } );
+
+    // Context fields are spread after the payload, so caller-supplied
+    // workflowId / runId / activityId cannot escape the executionContext.
+    expect( emitMock ).toHaveBeenCalledWith( 'external:cost:http:request', {
+      workflowId: 'wf-3',
+      runId: 'run-3',
+      activityId: 'act-3',
+      url: 'https://example.com'
+    } );
+  } );
+} );

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,15 +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';
-  TOKEN_USAGE: 'token_usage';
-};
+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,13 +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',
-  TOKEN_USAGE: 'token_usage'
-};
+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

@@ -16,8 +16,10 @@ export interface ErrorHookPayload {
  * Payload passed to the onWorkflowStart handler when a workflow run begins.
  */
 export interface WorkflowStartHookPayload {
-  /** Identifier of the workflow run. */
+  /** Workflow id (stable across retries / continue-as-new). */
   id: string;
+  /** Temporal run id for the current execution attempt. */
+  runId: string;
   /** Name of the workflow. */
   name: string;
 }
@@ -26,8 +28,10 @@ export interface WorkflowStartHookPayload {
  * Payload passed to the onWorkflowEnd handler when a workflow run completes successfully.
  */
 export interface WorkflowEndHookPayload {
-  /** Identifier of the workflow run. */
+  /** Workflow id (stable across retries / continue-as-new). */
   id: string;
+  /** Temporal run id for the current execution attempt. */
+  runId: string;
   /** Name of the workflow. */
   name: string;
   /** Duration of the workflow run in milliseconds. */
@@ -38,8 +42,10 @@ export interface WorkflowEndHookPayload {
  * Payload passed to the onWorkflowError handler when a workflow run fails.
  */
 export interface WorkflowErrorHookPayload {
-  /** Identifier of the workflow run. */
+  /** Workflow id (stable across retries / continue-as-new). */
   id: string;
+  /** Temporal run id for the current execution attempt. */
+  runId: string;
   /** Name of the workflow. */
   name: string;
   /** Elapsed time before failure in milliseconds. */
@@ -90,6 +96,37 @@ export declare function onWorkflowEnd( handler: ( payload: WorkflowEndHookPayloa
  */
 export declare function onWorkflowError( handler: ( payload: WorkflowErrorHookPayload ) => void ): void;
 
+/**
+ * Payload broadcast on the `http:request` event for every HTTP call issued
+ * through `@outputai/http`'s `fetch`. Fires for success, non-2xx, and network
+ * failure paths — `cost:http:request` continues to fire only when the consumer
+ * has attached a cost via `addRequestCost`.
+ *
+ * The framework auto-attaches `workflowId`, `runId`, and `activityId` onto the
+ * payload before broadcast, so consumers receive those identifiers in addition
+ * to the fields listed here.
+ */
+export interface HttpRequestHookPayload {
+  /** Workflow id (stable across retries / continue-as-new). */
+  workflowId: string;
+  /** Temporal run id for the current execution attempt. */
+  runId: string;
+  /** Activity / step id, when emitted from inside a step. */
+  activityId?: string;
+  /** UUID generated per request inside `@outputai/http`. */
+  requestId: string;
+  /** HTTP method (uppercase). */
+  method: string;
+  /** Absolute request URL. */
+  url: string;
+  /** HTTP status code; undefined on network failure. */
+  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';
+}
+
 /**
  * Register a handler to be invoked when a given event happens
  *

package/src/hooks/index.js

@@ -34,16 +34,16 @@ export const onBeforeWorkerStart = handler => messageBus.on( BusEventType.WORKER
   safeInvoke( handler, undefined, 'onBeforeWorkerStart' ) );
 
 /** Listen to workflow start events, excludes catalog workflow */
-export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { id, name } ) =>
-  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, name }, 'onWorkflowStart' ) : null );
+export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { id, runId, name } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, runId, name }, 'onWorkflowStart' ) : null );
 
 /** Listen to workflow end events, excludes catalog workflow */
-export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { id, name, duration } ) =>
-  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, name, duration }, 'onWorkflowEnd' ) : null );
+export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { id, runId, name, duration } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, runId, name, duration }, 'onWorkflowEnd' ) : null );
 
 /** Listen to workflow error events, excludes catalog workflow */
-export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { id, name, duration, error } ) =>
-  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, name, duration, error }, 'onWorkflowError' ) : null );
+export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { id, runId, name, duration, error } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, runId, name, duration, error }, 'onWorkflowError' ) : null );
 
 /** Generic listener for events emitted elsewhere (outside core) */
 export const on = ( eventName, handler ) => messageBus.on( `external:${eventName}`, payload =>

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

@@ -63,7 +63,18 @@ export type WorkflowContext<
      *
      * @see {@link https://docs.temporal.io/workflow-execution/workflowid-runid#workflow-id}
      */
-    workflowId: string
+    workflowId: string,
+
+    /**
+     * Internal Temporal run id for the current execution attempt.
+     *
+     * A single `workflowId` can map to multiple `runId`s when a workflow is
+     * retried, reset, or continued-as-new. The current run can be pinned in
+     * downstream `/workflow/{id}/runs/{rid}/...` API calls.
+     *
+     * @see {@link https://docs.temporal.io/workflow-execution/workflowid-runid#run-id}
+     */
+    runId: string
   }
 };
 

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 } );
 
@@ -39,15 +44,20 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
     // this returns a plain function, for example, in unit tests
     if ( !inWorkflowContext() ) {
       validateWithSchema( inputSchema, input, `Workflow ${name} input` );
-      const context = Context.build( { workflowId: 'test-workflow', continueAsNew: async () => {}, isContinueAsNewSuggested: () => false } );
+      const context = Context.build( {
+        workflowId: 'test-workflow',
+        runId: 'test-run',
+        continueAsNew: async () => {},
+        isContinueAsNewSuggested: () => false
+      } );
       const output = await fn( input, deepMerge( context, extra.context ) );
       validateWithSchema( outputSchema, output, `Workflow ${name} output` );
       return output;
     }
 
-    const { workflowId, memo, startTime } = workflowInfo();
+    const { workflowId, runId, memo, startTime } = workflowInfo();
 
-    const context = Context.build( { workflowId, continueAsNew, isContinueAsNewSuggested: () => workflowInfo().continueAsNewSuggested } );
+    const context = Context.build( { workflowId, runId, continueAsNew, isContinueAsNewSuggested: () => workflowInfo().continueAsNewSuggested } );
 
     // Root workflows will not have the execution context yet, since it is set here.
     const isRoot = !memo.executionContext;
@@ -57,6 +67,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
        It will be used to as context for tracing (connecting events) */
     const executionContext = memo.executionContext ?? {
       workflowId,
+      runId,
       workflowName: name,
       disableTrace,
       startTime: startTime.getTime()
@@ -69,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
@@ -91,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 );
@@ -110,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;
     }