@output.ai/core 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -39,6 +39,7 @@
     "redis": "5.8.3",
     "stacktrace-parser": "0.1.11",
     "undici": "7.18.2",
+    "winston": "3.17.0",
     "zod": "4.1.12"
   },
   "license": "Apache-2.0",
@@ -48,6 +49,7 @@
   "imports": {
     "#consts": "./src/consts.js",
     "#errors": "./src/errors.js",
+    "#logger": "./src/logger.js",
     "#utils": "./src/utils/index.js",
     "#tracing": "./src/tracing/internal_interface.js",
     "#async_storage": "./src/async_storage.js",

package/src/index.js

@@ -1,4 +1,4 @@
-import { evaluator, EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult } from './interface/evaluator.js';
+import { evaluator, EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult, EvaluationFeedback } from './interface/evaluator.js';
 import { step } from './interface/step.js';
 import { workflow } from './interface/workflow.js';
 import { executeInParallel } from './interface/workflow_utils.js';
@@ -16,6 +16,7 @@ export {
   EvaluationNumberResult,
   EvaluationStringResult,
   EvaluationBooleanResult,
+  EvaluationFeedback,
   // webhook tools
   executeInParallel,
   sendHttpRequest,

package/src/internal_activities/index.js

@@ -4,6 +4,9 @@ import { setMetadata, isStringboolTrue, serializeFetchResponse, serializeBodyAnd
 import { ComponentType } from '#consts';
 import * as localProcessor from '../tracing/processors/local/index.js';
 import * as s3Processor from '../tracing/processors/s3/index.js';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'HttpClient' );
 
 /**
  * Send a HTTP request.
@@ -42,7 +45,7 @@ export const sendHttpRequest = async ( { url, method, payload = undefined, heade
     }
   } )();
 
-  console.log( '[Core.sendHttpRequest]', response.status, response.statusText );
+  log.info( 'HTTP request completed', { url, method, status: response.status, statusText: response.statusText } );
 
   if ( !response.ok ) {
     throw new FatalError( `${method} ${url} ${response.status}` );

package/src/logger.d.ts

@@ -0,0 +1,4 @@
+import type { Logger } from 'winston';
+
+export declare const logger: Logger;
+export declare function createChildLogger( namespace: string ): Logger;

package/src/logger.js

@@ -0,0 +1,56 @@
+import winston from 'winston';
+
+const isProduction = process.env.NODE_ENV === 'production';
+
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  debug: 4
+};
+
+// Format metadata as friendly JSON: "{ name: "foo", count: 5 }"
+const formatMeta = obj => {
+  const entries = Object.entries( obj );
+  if ( !entries.length ) {
+    return '';
+  }
+  return ' { ' + entries.map( ( [ k, v ] ) => `${k}: ${JSON.stringify( v )}` ).join( ', ' ) + ' }';
+};
+
+// Development format: colorized with namespace prefix
+const devFormat = winston.format.combine(
+  winston.format.colorize(),
+  winston.format.printf( ( { level, message, namespace, service: _, environment: __, ...rest } ) => {
+    const ns = namespace ? `{Core.${namespace}}` : '{Core}';
+    const meta = formatMeta( rest );
+    return `[${level}] ${ns} ${message}${meta}`;
+  } )
+);
+
+// Production format: structured JSON
+const prodFormat = winston.format.combine(
+  winston.format.timestamp( { format: 'YYYY-MM-DDTHH:mm:ss.SSSZ' } ),
+  winston.format.errors( { stack: true } ),
+  winston.format.json()
+);
+
+export const logger = winston.createLogger( {
+  levels,
+  level: isProduction ? 'info' : 'debug',
+  format: isProduction ? prodFormat : devFormat,
+  defaultMeta: {
+    service: 'output-worker',
+    environment: process.env.NODE_ENV || 'development'
+  },
+  transports: [ new winston.transports.Console() ]
+} );
+
+/**
+ * Creates a child logger with a specific namespace
+ *
+ * @param {string} namespace - The namespace for this logger (e.g., 'Scanner', 'Tracing')
+ * @returns {winston.Logger} Child logger instance with namespace metadata
+ */
+export const createChildLogger = namespace => logger.child( { namespace } );

package/src/tracing/trace_engine.js

@@ -5,6 +5,9 @@ import { isStringboolTrue } from '#utils';
 import * as localProcessor from './processors/local/index.js';
 import * as s3Processor from './processors/s3/index.js';
 import { ComponentType } from '#consts';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Tracing' );
 
 const traceBus = new EventEmitter();
 const processors = [
@@ -32,7 +35,7 @@ export const init = async () => {
       try {
         await p.exec( ...args );
       } catch ( error ) {
-        console.error( `[Tracing] "${p.name}" processor execution error.`, error );
+        log.error( 'Processor execution error', { processor: p.name, error: error.message, stack: error.stack } );
       }
     } );
   }
@@ -44,7 +47,7 @@ export const init = async () => {
 const serializeDetails = details => details instanceof Error ? serializeError( details ) : details;
 
 /**
- * Creates a new trace event phase and sens to be written
+ * Creates a new trace event phase and sends it to be written
  *
  * @param {string} phase - The phase
  * @param {object} fields - All the trace fields

package/src/worker/catalog_workflow/index.js

@@ -2,6 +2,9 @@ import { z } from 'zod';
 import { dirname } from 'node:path';
 import { METADATA_ACCESS_SYMBOL } from '#consts';
 import { Catalog, CatalogActivity, CatalogWorkflow } from './catalog.js';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Catalog' );
 
 /**
  * Converts a Zod schema to JSON Schema format.
@@ -17,7 +20,7 @@ const convertToJsonSchema = schema => {
   try {
     return z.toJSONSchema( schema );
   } catch ( error ) {
-    console.warn( 'Invalid schema provided (expected Zod schema):', schema, error );
+    log.warn( 'Invalid schema provided (expected Zod schema)', { error: error.message } );
     return null;
   }
 };

package/src/worker/index.js

@@ -9,31 +9,34 @@ import { init as initTracing } from '#tracing';
 import { WORKFLOW_CATALOG } from '#consts';
 import { webpackConfigHook } from './bundler_options.js';
 import { initInterceptors } from './interceptors.js';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Worker' );
 
 // Get caller directory from command line arguments
 const callerDir = process.argv[2];
 
 ( async () => {
-  console.log( '[Core]', 'Loading workflows...', { callerDir } );
+  log.info( 'Loading workflows...', { callerDir } );
   const workflows = await loadWorkflows( callerDir );
 
-  console.log( '[Core]', 'Loading activities...', { callerDir } );
+  log.info( 'Loading activities...', { callerDir } );
   const activities = await loadActivities( callerDir, workflows );
 
-  console.log( '[Core]', 'Creating worker entry point...' );
+  log.info( 'Creating worker entry point...' );
   const workflowsPath = createWorkflowsEntryPoint( workflows );
 
-  console.log( '[Core]', 'Initializing tracing...' );
+  log.info( 'Initializing tracing...' );
   await initTracing();
 
-  console.log( '[Core]', 'Creating workflows catalog...' );
+  log.info( 'Creating workflows catalog...' );
   const catalog = createCatalog( { workflows, activities } );
 
-  console.log( '[Core]', 'Connecting Temporal...' );
-  // enable TLS only when connecting remove (api key is present)
+  log.info( 'Connecting Temporal...' );
+  // Enable TLS when connecting to remote Temporal (API key present)
   const connection = await NativeConnection.connect( { address, tls: Boolean( apiKey ), apiKey } );
 
-  console.log( '[Core]', 'Creating worker...' );
+  log.info( 'Creating worker...' );
   const worker = await Worker.create( {
     connection,
     namespace,
@@ -47,7 +50,7 @@ const callerDir = process.argv[2];
     bundlerOptions: { webpackConfigHook }
   } );
 
-  console.log( '[Core]', 'Starting catalog workflow...' );
+  log.info( 'Starting catalog workflow...' );
   await new Client( { connection, namespace } ).workflow.start( WORKFLOW_CATALOG, {
     taskQueue,
     workflowId: catalogId, // use the name of the task queue as the catalog name, ensuring uniqueness
@@ -55,7 +58,7 @@ const callerDir = process.argv[2];
     args: [ catalog ]
   } );
 
-  console.log( '[Core]', 'Running worker...' );
+  log.info( 'Running worker...' );
 
   // FORCE_QUIT_GRACE_MS delays the second instance of a shutdown command.
   // If running output-worker directly with npx, 2 signals are recieved in
@@ -69,12 +72,12 @@ const callerDir = process.argv[2];
       if ( elapsed < FORCE_QUIT_GRACE_MS ) {
         return; // ignore rapid duplicate signals
       }
-      process.stderr.write( '[Core] Force quitting...\n' );
+      log.warn( 'Force quitting...' );
       process.exit( 1 );
     }
     state.isShuttingDown = true;
     state.shutdownStartedAt = Date.now();
-    process.stderr.write( `[Core] Received ${signal}, shutting down...\n` );
+    log.info( 'Shutting down...', { signal } );
     worker.shutdown();
   };
 
@@ -82,13 +85,13 @@ const callerDir = process.argv[2];
   process.on( 'SIGINT', () => shutdown( 'SIGINT' ) );
 
   await worker.run();
-  process.stderr.write( '[Core] Worker stopped.\n' );
+  log.info( 'Worker stopped.' );
 
   await connection.close();
-  process.stderr.write( '[Core] Connection closed.\n' );
+  log.info( 'Connection closed.' );
 
   process.exit( 0 );
 } )().catch( error => {
-  process.stderr.write( `[Core] Fatal error: ${error.message}\n` );
+  log.error( 'Fatal error', { message: error.message, stack: error.stack } );
   process.exit( 1 );
 } );

package/src/worker/loader.js

@@ -12,6 +12,9 @@ import {
   WORKFLOW_CATALOG,
   ACTIVITY_GET_TRACE_DESTINATIONS
 } from '#consts';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Scanner' );
 
 const __dirname = dirname( fileURLToPath( import.meta.url ) );
 
@@ -64,7 +67,7 @@ export async function loadActivities( rootDir, workflows ) {
   for ( const { path: workflowPath, name: workflowName } of workflows ) {
     const dir = dirname( workflowPath );
     for await ( const { fn, metadata, path } of importComponents( dir, Object.values( activityMatchersBuilder( dir ) ) ) ) {
-      console.log( '[Core.Scanner]', 'Component loaded:', metadata.type, metadata.name, 'at', path );
+      log.info( 'Component loaded', { type: metadata.type, name: metadata.name, path, workflow: workflowName } );
       // Activities loaded from a workflow path will use the workflow name as a namespace, which is unique across the platform, avoiding collision
       const activityKey = generateActivityKey( { namespace: workflowName, activityName: metadata.name } );
       activities[activityKey] = fn;
@@ -75,7 +78,7 @@ export async function loadActivities( rootDir, workflows ) {
 
   // Load shared activities/evaluators
   for await ( const { fn, metadata, path } of importComponents( rootDir, [ staticMatchers.sharedStepsDir, staticMatchers.sharedEvaluatorsDir ] ) ) {
-    console.log( '[Core.Scanner]', 'Component loaded: shared ', metadata.type, metadata.name, 'at', path );
+    log.info( 'Shared component loaded', { type: metadata.type, name: metadata.name, path } );
     // The namespace for shared activities is fixed
     const activityKey = generateActivityKey( { namespace: SHARED_STEP_PREFIX, activityName: metadata.name } );
     activities[activityKey] = fn;
@@ -105,7 +108,7 @@ export async function loadWorkflows( rootDir ) {
     if ( staticMatchers.workflowPathHasShared( path ) ) {
       throw new Error( 'Workflow directory can\'t be named "shared"' );
     }
-    console.log( '[Core.Scanner]', 'Workflow loaded:', metadata.name, 'at', path );
+    log.info( 'Workflow loaded', { name: metadata.name, path } );
     workflows.push( { ...metadata, path } );
   }
   return workflows;

package/src/worker/sinks.js

@@ -1,12 +1,15 @@
 import { WORKFLOW_CATALOG } from '#consts';
 import { addEventStart, addEventEnd, addEventError } from '#tracing';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Worker' );
 
 /**
  * Start a workflow trace event
  *
  * @param {function} method - Trace function to call
  * @param {object} workflowInfo - Temporal workflowInfo object
- * @param {object} details - Teh details to attach to the event
+ * @param {object} details - The details to attach to the event
  */
 const addWorkflowEvent = ( method, workflowInfo, details ) => {
   const { workflowId: id, workflowType: name, memo: { parentId, executionContext } } = workflowInfo;
@@ -16,6 +19,47 @@ const addWorkflowEvent = ( method, workflowInfo, details ) => {
   method( { id, kind: 'workflow', name, details, parentId, executionContext } );
 };
 
+/**
+ * Log workflow start
+ *
+ * @param {object} workflowInfo - Temporal workflowInfo object
+ */
+const logWorkflowStart = workflowInfo => {
+  const { workflowId, workflowType: workflowName } = workflowInfo;
+  if ( workflowName === WORKFLOW_CATALOG ) {
+    return;
+  }
+  log.info( 'Workflow started', { workflowName, workflowId } );
+};
+
+/**
+ * Log workflow completion with duration
+ *
+ * @param {object} workflowInfo - Temporal workflowInfo object
+ */
+const logWorkflowEnd = workflowInfo => {
+  const { workflowId, workflowType: workflowName, startTime } = workflowInfo;
+  if ( workflowName === WORKFLOW_CATALOG ) {
+    return;
+  }
+  const durationMs = Date.now() - startTime.getTime();
+  log.info( 'Workflow completed', { workflowName, workflowId, durationMs } );
+};
+
+/**
+ * Log workflow failure with duration
+ *
+ * @param {object} workflowInfo - Temporal workflowInfo object
+ */
+const logWorkflowError = workflowInfo => {
+  const { workflowId, workflowType: workflowName, startTime } = workflowInfo;
+  if ( workflowName === WORKFLOW_CATALOG ) {
+    return;
+  }
+  const durationMs = Date.now() - startTime.getTime();
+  log.error( 'Workflow failed', { workflowName, workflowId, durationMs } );
+};
+
 /**
  * Start a trace event with given configuration
  *
@@ -33,17 +77,26 @@ const addEvent = ( method, workflowInfo, options ) => {
 export const sinks = {
   trace: {
     addWorkflowEventStart: {
-      fn: ( ...args ) => addWorkflowEvent( addEventStart, ...args ),
+      fn: ( workflowInfo, ...rest ) => {
+        logWorkflowStart( workflowInfo );
+        addWorkflowEvent( addEventStart, workflowInfo, ...rest );
+      },
       callDuringReplay: false
     },
 
     addWorkflowEventEnd: {
-      fn: ( ...args ) => addWorkflowEvent( addEventEnd, ...args ),
+      fn: ( workflowInfo, ...rest ) => {
+        logWorkflowEnd( workflowInfo );
+        addWorkflowEvent( addEventEnd, workflowInfo, ...rest );
+      },
       callDuringReplay: false
     },
 
     addWorkflowEventError: {
-      fn: ( ...args ) => addWorkflowEvent( addEventError, ...args ),
+      fn: ( workflowInfo, ...rest ) => {
+        logWorkflowError( workflowInfo );
+        addWorkflowEvent( addEventError, workflowInfo, ...rest );
+      },
       callDuringReplay: false
     },