@outputai/core 0.8.2-next.42a0ddf.0 → 0.8.2-next.ad732b1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.8.2-next.42a0ddf.0",
+  "version": "0.8.2-next.ad732b1.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -12,9 +12,13 @@
       "types": "./src/hooks/index.d.ts",
       "import": "./src/hooks/index.js"
     },
-    "./sdk_activity_integration": {
-      "types": "./src/activity_integration/index.d.ts",
-      "import": "./src/activity_integration/index.js"
+    "./sdk/helpers": {
+      "types": "./src/sdk/helpers/index.d.ts",
+      "import": "./src/sdk/helpers/index.js"
+    },
+    "./sdk/runtime": {
+      "types": "./src/sdk/runtime/index.d.ts",
+      "import": "./src/sdk/runtime/index.js"
     },
     "./sdk_utils": {
       "types": "./src/utils/index.d.ts",

package/src/consts.js

@@ -2,6 +2,7 @@ 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 ACTIVITY_LOGGER_SYMBOL = Symbol.for( '__activity_logger' );
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const SHARED_STEP_PREFIX = '$shared';
 export const WORKFLOW_CATALOG = '$catalog';
@@ -24,13 +25,15 @@ export const LifecycleEvent = {
 export const BusEventType = {
   WORKER_BEFORE_START: 'worker:before_start',
 
-  WORKFLOW_START: 'workflow:start',
   WORKFLOW_END: 'workflow:end',
   WORKFLOW_ERROR: 'workflow:error',
+  WORKFLOW_LOG: 'workflow:log',
+  WORKFLOW_START: 'workflow:start',
 
-  ACTIVITY_START: 'activity:start',
   ACTIVITY_END: 'activity:end',
   ACTIVITY_ERROR: 'activity:error',
+  ACTIVITY_LOG: 'activity:log',
+  ACTIVITY_START: 'activity:start',
 
   RUNTIME_ERROR: 'runtime_error'
 };

package/src/interface/evaluator.js

@@ -1,5 +1,5 @@
 import { EvaluatorValidator } from './validations/index.js';
-import { setMetadata } from '#utils';
+import { setMetadata } from '#internal_utils/component';
 import { ComponentType } from '#consts';
 
 /**

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 * as Logger 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 * as Logger from './logger.js';
 
 export {
   evaluator,
   step,
   workflow,
+  Logger,
   EvaluationNumberResult,
   EvaluationStringResult,
   EvaluationBooleanResult,

package/src/interface/logger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Additional structured fields attached to a log record.
+ */
+export type LogMetadata = Record<string, unknown>;
+
+/**
+ * Log an error (level 0)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function error( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log a warn (level 1)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function warn( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log an info (level 2)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function info( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log http (level 3)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function http( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log verbose (level 4)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function verbose( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log debug (level 5)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function debug( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log silly (level 6)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function silly( message: string, metadata?: LogMetadata ) : void;

package/src/interface/logger.js

@@ -0,0 +1,68 @@
+import { inWorkflowContext } from '@temporalio/workflow';
+import { proxySinks } from '@temporalio/workflow';
+import { ACTIVITY_LOGGER_SYMBOL } from '#consts';
+import { isPlainObject } from '#utils';
+
+const reservedMetadataFields = new Set( [
+  // Winston fields
+  'label',
+  'level',
+  'message',
+  'metadata',
+  'namespace',
+  '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();
+
+// Convert npm log levels to console levels
+const levelToConsole = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  http: 'log',
+  verbose: 'log',
+  debug: 'debug',
+  silly: 'log'
+};
+
+/** Drops reserved keys from object */
+const removeReservedFields = obj => Object.fromEntries( Object.entries( obj ).filter( ( [ k ] ) => !reservedMetadataFields.has( k ) ) );
+
+const log = ( level, message, metadata ) => {
+  const sanitized = {
+    message: String( message ),
+    ...( isPlainObject( metadata ) && { 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 );
+  }
+};
+
+// Winston uses npm levels by default: https://github.com/winstonjs/winston#logging-levels
+export const error = log.bind( null, 'error' );
+export const warn = log.bind( null, 'warn' );
+export const info = log.bind( null, 'info' );
+export const http = log.bind( null, 'http' );
+export const verbose = log.bind( null, 'verbose' );
+export const debug = log.bind( null, 'debug' );
+export const silly = log.bind( null, 'silly' );

package/src/interface/logger.spec.js

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ACTIVITY_LOGGER_SYMBOL } from '#consts';
+
+const workflowLogMock = vi.fn();
+const proxySinksMock = vi.fn( () => ( {
+  workflow: {
+    log: workflowLogMock
+  }
+} ) );
+const inWorkflowContextMock = vi.fn( () => false );
+
+vi.mock( '@temporalio/workflow', () => ( {
+  inWorkflowContext: inWorkflowContextMock,
+  proxySinks: proxySinksMock
+} ) );
+
+const logLevels = [
+  'error',
+  'warn',
+  'info',
+  'http',
+  'verbose',
+  'debug',
+  'silly'
+];
+
+const consoleMethodsByLevel = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  http: 'log',
+  verbose: 'log',
+  debug: 'debug',
+  silly: 'log'
+};
+
+const loadLogger = async () => import( './logger.js' );
+
+describe( 'interface/logger', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    inWorkflowContextMock.mockReturnValue( false );
+    delete globalThis[ACTIVITY_LOGGER_SYMBOL];
+  } );
+
+  afterEach( () => {
+    delete globalThis[ACTIVITY_LOGGER_SYMBOL];
+    vi.restoreAllMocks();
+  } );
+
+  it( 'proxies sinks once when the module is loaded', async () => {
+    await loadLogger();
+
+    expect( proxySinksMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'logs every level through workflow sinks inside workflow context', async () => {
+    const logger = await loadLogger();
+    inWorkflowContextMock.mockReturnValue( true );
+
+    logLevels.forEach( level => {
+      logger[level]( `${level} message`, { requestId: level } );
+    } );
+
+    logLevels.forEach( ( level, index ) => {
+      const payload = {
+        level,
+        message: `${level} message`,
+        metadata: { requestId: level }
+      };
+
+      expect( workflowLogMock ).toHaveBeenNthCalledWith( index + 1, payload );
+    } );
+  } );
+
+  it( 'sanitizes messages and metadata before logging', async () => {
+    const logger = await loadLogger();
+    inWorkflowContextMock.mockReturnValue( true );
+
+    logger.info( 123, {
+      requestId: 'req-1',
+      level: 'error',
+      message: 'metadata message'
+    } );
+
+    expect( workflowLogMock ).toHaveBeenCalledWith( {
+      level: 'info',
+      message: '123',
+      metadata: { requestId: 'req-1' }
+    } );
+  } );
+
+  it( 'logs every level through the activity global logger when it is set outside workflow context', async () => {
+    const logger = await loadLogger();
+    const activityLoggerMock = vi.fn();
+    globalThis[ACTIVITY_LOGGER_SYMBOL] = activityLoggerMock;
+
+    logLevels.forEach( level => {
+      logger[level]( `${level} message`, { requestId: level } );
+    } );
+
+    logLevels.forEach( ( level, index ) => {
+      expect( activityLoggerMock ).toHaveBeenNthCalledWith( index + 1, {
+        level,
+        message: `${level} message`,
+        metadata: { requestId: level }
+      } );
+    } );
+    expect( workflowLogMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'logs every level to its native console method when no workflow or activity logger is available', async () => {
+    const logger = await loadLogger();
+    const consoleMocks = Object.fromEntries(
+      [ 'debug', 'error', 'info', 'log', 'warn' ].map( method => [
+        method,
+        vi.spyOn( console, method ).mockImplementation( () => {} )
+      ] )
+    );
+
+    logLevels.forEach( level => {
+      logger[level]( `${level} message`, { requestId: level } );
+    } );
+
+    logLevels.forEach( level => {
+      expect( consoleMocks[consoleMethodsByLevel[level]] ).toHaveBeenCalledWith(
+        `${level} message`,
+        { requestId: level }
+      );
+    } );
+    expect( consoleMocks.error ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.warn ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.info ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.debug ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.log ).toHaveBeenCalledTimes( 3 );
+    expect( workflowLogMock ).not.toHaveBeenCalled();
+  } );
+} );

package/src/interface/step.js

@@ -1,5 +1,5 @@
 import { StepValidator } from './validations/index.js';
-import { setMetadata } from '#utils';
+import { setMetadata } from '#internal_utils/component';
 import { ComponentType } from '#consts';
 
 /**

package/src/interface/workflow.js

@@ -1,8 +1,9 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy } from '@temporalio/workflow';
 import { WorkflowValidator } from './validations/index.js';
-import { deepMerge, setMetadata, toUrlSafeBase64 } from '#utils';
+import { deepMerge, toUrlSafeBase64 } from '#utils';
 import { WorkflowContext } from '#internal_utils/workflow_context';
+import { setMetadata } from '#internal_utils/component';
 import { TraceInfo } from '#internal_utils/trace_info';
 import { defaultOptions } from './workflow_activity_options.js';
 import {

package/src/internal_activities/index.js

@@ -1,6 +1,7 @@
 import { FatalError } from '#errors';
 import { fetch } from 'undici';
-import { setMetadata, serializeFetchResponse, serializeBodyAndInferContentType } from '#utils';
+import { serializeFetchResponse, serializeBodyAndInferContentType } from '#utils';
+import { setMetadata } from '#internal_utils/component';
 import { ComponentType } from '#consts';
 import { createChildLogger } from '#logger';
 import { getDestinations } from '#tracing';

package/src/internal_utils/component.js

@@ -0,0 +1,9 @@
+import { METADATA_ACCESS_SYMBOL } from '#consts';
+
+/**
+ * Add metadata "values" property to a given object
+ * @param {object} target
+ * @param {object} values
+ */
+export const setMetadata = ( target, values ) =>
+  Object.defineProperty( target, METADATA_ACCESS_SYMBOL, { value: values, writable: false, enumerable: false, configurable: false } );

package/src/logger/development.js

@@ -47,7 +47,7 @@ const getColor = v =>
   assignedColors.get( v ) ?? assignedColors.set( v, COLORS[assignedColors.size % COLORS.length] ).get( v );
 
 export const options = {
-  level: 'debug',
+  level: process.env.OUTPUT_LOG_LEVEL ?? 'debug',
   transports: [ new transports.Console() ],
   format: format.combine(
     format.colorize(),

package/src/logger/development.spec.js

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 const LEVEL = Symbol.for( 'level' );
 const MESSAGE = Symbol.for( 'message' );
@@ -14,6 +14,10 @@ const loadDevelopmentLogger = async () => {
 };
 
 describe( 'logger/development', () => {
+  afterEach( () => {
+    vi.unstubAllEnvs();
+  } );
+
   describe( 'formatJson', () => {
     it( 'formats nested plain objects and arrays', async () => {
       const { formatJson } = await loadDevelopmentLogger();
@@ -40,6 +44,19 @@ describe( 'logger/development', () => {
   } );
 
   describe( 'options.format', () => {
+    it( 'uses debug level by default', async () => {
+      const { options } = await loadDevelopmentLogger();
+
+      expect( options.level ).toBe( 'debug' );
+    } );
+
+    it( 'uses OUTPUT_LOG_LEVEL when configured', async () => {
+      vi.stubEnv( 'OUTPUT_LOG_LEVEL', 'http' );
+      const { options } = await loadDevelopmentLogger();
+
+      expect( options.level ).toBe( 'http' );
+    } );
+
     it( 'formats level, namespace, message, and metadata fields', async () => {
       const { options } = await loadDevelopmentLogger();
       const info = options.format.transform( {

package/src/logger/production.js

@@ -1,7 +1,7 @@
 import { transports, format } from 'winston';
 
 export const options = {
-  level: 'info',
+  level: process.env.OUTPUT_LOG_LEVEL ?? 'info',
   transports: [ new transports.Console() ],
   defaultMeta: {
     service: 'output-worker',

package/src/logger/production.spec.js

@@ -1,11 +1,21 @@
-import { describe, expect, it } from 'vitest';
-import { options } from './production.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 const LEVEL = Symbol.for( 'level' );
 const MESSAGE = Symbol.for( 'message' );
 
+const loadProductionLogger = async () => {
+  vi.resetModules();
+  return import( './production.js' );
+};
+
 describe( 'logger/production', () => {
-  it( 'uses info level and default production metadata', () => {
+  afterEach( () => {
+    vi.unstubAllEnvs();
+  } );
+
+  it( 'uses info level and default production metadata', async () => {
+    const { options } = await loadProductionLogger();
+
     expect( options.level ).toBe( 'info' );
     expect( options.defaultMeta ).toEqual( {
       service: 'output-worker',
@@ -13,7 +23,15 @@ describe( 'logger/production', () => {
     } );
   } );
 
-  it( 'formats logs as JSON with timestamp and metadata fields', () => {
+  it( 'uses OUTPUT_LOG_LEVEL when configured', async () => {
+    vi.stubEnv( 'OUTPUT_LOG_LEVEL', 'debug' );
+    const { options } = await loadProductionLogger();
+
+    expect( options.level ).toBe( 'debug' );
+  } );
+
+  it( 'formats logs as JSON with timestamp and metadata fields', async () => {
+    const { options } = await loadProductionLogger();
     const info = options.format.transform( {
       [LEVEL]: 'info',
       level: 'info',
@@ -33,7 +51,8 @@ describe( 'logger/production', () => {
     expect( output.timestamp ).toEqual( expect.stringMatching( /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}$/u ) );
   } );
 
-  it( 'includes error stack when formatting Error messages', () => {
+  it( 'includes error stack when formatting Error messages', async () => {
+    const { options } = await loadProductionLogger();
     const error = new Error( 'boom' );
     const info = options.format.transform( {
       [LEVEL]: 'error',

package/src/sdk/README.md

@@ -0,0 +1,47 @@
+## SDK integration API for Output packages
+
+**THESE MODULES ARE NOT PUBLIC. DO NOT IMPORT THEM ON YOUR PROJECT.**
+
+This folder contains integration helpers used by other Output SDK packages.
+
+The two subfolders represent a hard Temporal boundary. Code imported by
+workflow-bundled modules must only depend on `helpers`. Code that needs worker
+or activity runtime state belongs in `runtime`.
+
+Do not change these without reviewing call-sites.
+
+### `helpers`
+
+Helpers must be safe to import while Temporal workflows are bundled and executed
+in the workflow sandbox.
+
+Allowed:
+
+- Stateless functions and namespace objects.
+- Deterministic code with no runtime side effects at import time.
+- Imports from other sandbox-safe helper modules.
+- Small, dependency-free helpers for any deterministic computation that can run
+  without worker or activity state.
+
+Not allowed:
+
+- Access to activity context, async storage, sinks, tracing state, workers, or
+  clients.
+- Imports from `@temporalio/activity`, `@temporalio/worker`, or Node-only APIs
+  that cannot be bundled into workflow code.
+- Process, filesystem, network, clock, randomness, or environment access unless
+  the behavior is known to be safe and deterministic in the workflow sandbox.
+- Any import chain that reaches `runtime`.
+
+If a helper cannot satisfy these rules, put it in `runtime` instead.
+
+### `runtime`
+
+Runtime modules are for helpers that need Output or Temporal runtime state.
+
+Use `runtime` for activity-only integrations such as context lookup, event
+emission, tracing, async storage, worker state, sinks, and other behavior that is
+not safe inside workflow-bundled code.
+
+Runtime modules may depend on activity runtime APIs and internal state, but they
+must not be imported by workflow-safe code.

package/src/sdk/helpers/component_metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tools to extract data from Outputai Core Components metadata storage
+ */
+export declare const ComponentMetadata: {
+  /**
+   * Extract the name from a workflow(), step() or evaluator() return
+   * @param fn
+   * @returns
+   */
+  getName( fn: Function ): string | undefined;
+
+  /**
+   * Check if a function has metadata from workflow(), step() or evaluator()
+   * @param fn
+   */
+  has( fn: Function ): boolean;
+};

package/src/sdk/helpers/component_metadata.js

@@ -0,0 +1,6 @@
+import { METADATA_ACCESS_SYMBOL } from '#consts';
+
+export const ComponentMetadata = {
+  getName: fn => fn[METADATA_ACCESS_SYMBOL]?.name,
+  has: fn => !!fn[METADATA_ACCESS_SYMBOL]
+};

package/src/sdk/helpers/component_metadata.spec.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { METADATA_ACCESS_SYMBOL } from '#consts';
+import { ComponentMetadata } from './component_metadata.js';
+
+describe( 'ComponentMetadata', () => {
+  it( 'detects functions tagged with component metadata', () => {
+    const component = () => {};
+    Object.defineProperty( component, METADATA_ACCESS_SYMBOL, {
+      value: { name: 'my_component' }
+    } );
+
+    expect( ComponentMetadata.has( component ) ).toBe( true );
+  } );
+
+  it( 'returns the component metadata name', () => {
+    const component = () => {};
+    Object.defineProperty( component, METADATA_ACCESS_SYMBOL, {
+      value: { name: 'my_component' }
+    } );
+
+    expect( ComponentMetadata.getName( component ) ).toBe( 'my_component' );
+  } );
+
+  it( 'returns false and undefined for untagged functions', () => {
+    const fn = () => {};
+
+    expect( ComponentMetadata.has( fn ) ).toBe( false );
+    expect( ComponentMetadata.getName( fn ) ).toBeUndefined();
+  } );
+} );

package/src/sdk/helpers/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * > [!WARNING]
+ * > **Internal use only.** Not part of the public API; may change without notice.
+ *
+ * These are stateless helpers for other SDK modules integration.
+ * They can be used while Temporal workflows are bundled.
+ *
+ * @packageDocumentation
+ */
+export * from './component_metadata.js';
+export * from './path.js';

package/src/sdk/helpers/index.js

@@ -0,0 +1,2 @@
+export * from './component_metadata.js';
+export * from './path.js';

package/src/sdk/helpers/path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tools to interact with filesystem paths
+ */
+export declare const Path: {
+  /**
+   * Return the first immediate directory of the file invoking the code that called this function.
+   *
+   * Excludes `@outputai/core`, node, other internal paths, and any additional ignore paths.
+   */
+  resolveInvocationDir( additionalIgnorePaths?: string[] ): string
+};

package/src/sdk/helpers/path.js

@@ -0,0 +1,32 @@
+import * as stackTraceParser from 'stacktrace-parser';
+
+// OS separator, but in a deterministic way, allowing this to work in Temporal's sandbox
+// This avoids importing from node:path
+const SEP = new Error().stack.includes( '/' ) ? '/' : '\\';
+const transformSeparators = path => path.replaceAll( '/', SEP );
+
+const defaultIgnorePaths = [
+  '/@outputai/core/',
+  '/@outputai/llm/',
+  '/@outputai/evals/',
+  '/sdk/core/',
+  '/sdk/llm/',
+  '/sdk/evals/',
+  'node:internal/',
+  'evalmachine.',
+  'webpack/bootstrap'
+];
+
+export const Path = {
+  resolveInvocationDir: ( additionalIgnorePaths = [] ) => {
+    const stack = new Error().stack;
+    const lines = stackTraceParser.parse( stack );
+    const ignorePaths = [ ...additionalIgnorePaths, ...defaultIgnorePaths ].map( transformSeparators );
+
+    const frame = lines.find( l => !ignorePaths.some( p => l.file.includes( p ) ) );
+    if ( !frame ) {
+      throw new Error( `Invocation dir resolution via stack trace failed. Stack: ${stack}` );
+    }
+    return frame.file.replace( 'file://', '' ).split( SEP ).slice( 0, -1 ).join( SEP );
+  }
+};