@output.ai/core 0.3.11-dev.pr311-3950092 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.3.11-dev.pr311-3950092",
+  "version": "0.4.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/internal_activities/index.js

@@ -66,8 +66,8 @@ setMetadata( sendHttpRequest, { type: ComponentType.INTERNAL_STEP } );
  * @returns {object} Information about enabled workflows
  */
 export const getTraceDestinations = ( { startTime, workflowId, workflowName } ) => ( {
-  local: isStringboolTrue( process.env.TRACE_LOCAL_ON ) ? localProcessor.getDestination( { startTime, workflowId, workflowName } ) : null,
-  remote: isStringboolTrue( process.env.TRACE_REMOTE_ON ) ? s3Processor.getDestination( { startTime, workflowId, workflowName } ) : null
+  local: isStringboolTrue( process.env.OUTPUT_TRACE_LOCAL_ON ) ? localProcessor.getDestination( { startTime, workflowId, workflowName } ) : null,
+  remote: isStringboolTrue( process.env.OUTPUT_TRACE_REMOTE_ON ) ? s3Processor.getDestination( { startTime, workflowId, workflowName } ) : null
 } );
 
 setMetadata( getTraceDestinations, { type: ComponentType.INTERNAL_STEP } );

package/src/tracing/processors/local/index.js

@@ -43,7 +43,7 @@ const resolveIOPath = workflowName => join( callerDir, 'logs', resolveTraceFolde
  * Resolves the file path to be reported as the trace destination.
  *
  * Considering that in containerized environments (e.g., Docker), the file path might differ from the host machine,
- * this value takes in consideration the TRACE_HOST_PATH env variable instead of the local filesystem to mount
+ * this value takes in consideration the OUTPUT_TRACE_HOST_PATH env variable instead of the local filesystem to mount
  * the final file path.
  *
  * If the env variable is not present, it falls back to the same value used to write files locally.
@@ -51,8 +51,8 @@ const resolveIOPath = workflowName => join( callerDir, 'logs', resolveTraceFolde
  * @param {string} workflowName - The name of the workflow
  * @returns {string} The path to report, reflecting the actual filesystem
  */
-const resolveReportPath = workflowName => process.env.TRACE_HOST_PATH ?
-  join( process.env.TRACE_HOST_PATH, resolveTraceFolder( workflowName ) ) :
+const resolveReportPath = workflowName => process.env.OUTPUT_TRACE_HOST_PATH ?
+  join( process.env.OUTPUT_TRACE_HOST_PATH, resolveTraceFolder( workflowName ) ) :
   resolveIOPath( workflowName );
 
 /**
@@ -99,7 +99,7 @@ export const exec = ( { entry, executionContext } ) => {
 /**
  * Returns where the trace is saved as an absolute path.
  *
- * This uses the optional TRACE_HOST_PATH to return values relative to the host OS, not the container, if applicable.
+ * This uses the optional OUTPUT_TRACE_HOST_PATH to return values relative to the host OS, not the container, if applicable.
  *
  * @param {object} args
  * @param {string} args.startTime - The start time of the workflow

package/src/tracing/processors/local/index.spec.js

@@ -29,7 +29,7 @@ describe( 'tracing/processors/local', () => {
     vi.clearAllMocks();
     store.files.clear();
     process.argv[2] = '/tmp/project';
-    delete process.env.TRACE_HOST_PATH; // Clear TRACE_HOST_PATH for clean tests
+    delete process.env.OUTPUT_TRACE_HOST_PATH; // Clear OUTPUT_TRACE_HOST_PATH for clean tests
   } );
 
   it( 'init(): creates temp dir and cleans up old files', async () => {
@@ -62,7 +62,7 @@ describe( 'tracing/processors/local', () => {
 
     expect( writeFileSyncMock ).toHaveBeenCalledTimes( 3 );
     const [ writtenPath, content ] = writeFileSyncMock.mock.calls.at( -1 );
-    // Changed: Now uses process.cwd() + '/logs' fallback when TRACE_HOST_PATH not set
+    // Changed: Now uses process.cwd() + '/logs' fallback when OUTPUT_TRACE_HOST_PATH not set
     expect( writtenPath ).toMatch( /\/runs\/WF\// );
     expect( JSON.parse( content.trim() ).count ).toBe( 3 );
   } );
@@ -81,11 +81,11 @@ describe( 'tracing/processors/local', () => {
     expect( destination ).toContain( '/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 
-  it( 'exec(): writes to container path regardless of TRACE_HOST_PATH', async () => {
+  it( 'exec(): writes to container path regardless of OUTPUT_TRACE_HOST_PATH', async () => {
     const { exec, init } = await import( './index.js' );
 
-    // Set TRACE_HOST_PATH to simulate Docker environment
-    process.env.TRACE_HOST_PATH = '/host/path/logs';
+    // Set OUTPUT_TRACE_HOST_PATH to simulate Docker environment
+    process.env.OUTPUT_TRACE_HOST_PATH = '/host/path/logs';
 
     init();
 
@@ -97,16 +97,16 @@ describe( 'tracing/processors/local', () => {
     expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
     const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
 
-    // Should write to process.cwd()/logs, NOT to TRACE_HOST_PATH
+    // Should write to process.cwd()/logs, NOT to OUTPUT_TRACE_HOST_PATH
     expect( writtenPath ).not.toContain( '/host/path/logs' );
     expect( writtenPath ).toMatch( /logs\/runs\/WF\// );
   } );
 
-  it( 'getDestination(): returns TRACE_HOST_PATH when set', async () => {
+  it( 'getDestination(): returns OUTPUT_TRACE_HOST_PATH when set', async () => {
     const { getDestination } = await import( './index.js' );
 
-    // Set TRACE_HOST_PATH to simulate Docker environment
-    process.env.TRACE_HOST_PATH = '/host/path/logs';
+    // Set OUTPUT_TRACE_HOST_PATH to simulate Docker environment
+    process.env.OUTPUT_TRACE_HOST_PATH = '/host/path/logs';
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
     const workflowId = 'workflow-id-123';
@@ -114,15 +114,15 @@ describe( 'tracing/processors/local', () => {
 
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Should return TRACE_HOST_PATH-based path for reporting
+    // Should return OUTPUT_TRACE_HOST_PATH-based path for reporting
     expect( destination ).toBe( '/host/path/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 
   it( 'separation of write and report paths works correctly', async () => {
     const { exec, getDestination, init } = await import( './index.js' );
 
-    // Set TRACE_HOST_PATH to simulate Docker environment
-    process.env.TRACE_HOST_PATH = '/Users/ben/project/logs';
+    // Set OUTPUT_TRACE_HOST_PATH to simulate Docker environment
+    process.env.OUTPUT_TRACE_HOST_PATH = '/Users/ben/project/logs';
 
     init();
 
@@ -142,7 +142,7 @@ describe( 'tracing/processors/local', () => {
     expect( writtenPath ).not.toContain( '/Users/ben/project' );
     expect( writtenPath ).toMatch( /logs\/runs\/test-workflow\// );
 
-    // Verify report path uses TRACE_HOST_PATH
+    // Verify report path uses OUTPUT_TRACE_HOST_PATH
     expect( destination ).toBe( '/Users/ben/project/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 } );

package/src/tracing/processors/s3/index.js

@@ -59,4 +59,4 @@ export const exec = async ( { entry, executionContext } ) => {
  * @returns {string} The S3 url of the trace file
  */
 export const getDestination = ( { startTime, workflowId, workflowName } ) =>
-  `https://${process.env.TRACE_REMOTE_S3_BUCKET}.s3.amazonaws.com/${getS3Key( { workflowId, workflowName, startTime } )}`;
+  `https://${process.env.OUTPUT_TRACE_REMOTE_S3_BUCKET}.s3.amazonaws.com/${getS3Key( { workflowId, workflowName, startTime } )}`;

package/src/tracing/processors/s3/index.spec.js

@@ -18,7 +18,7 @@ vi.mock( '../../tools/build_trace_tree.js', () => ( { default: buildTraceTreeMoc
 describe( 'tracing/processors/s3', () => {
   beforeEach( () => {
     vi.clearAllMocks();
-    process.env.TRACE_REMOTE_S3_BUCKET = 'bkt';
+    process.env.OUTPUT_TRACE_REMOTE_S3_BUCKET = 'bkt';
   } );
 
   it( 'init(): ensures redis client is created', async () => {

package/src/tracing/processors/s3/redis_client.js

@@ -1,63 +1,19 @@
 import { createClient } from 'redis';
 import { throws } from '#utils';
-import { createChildLogger } from '#logger';
 
-const log = createChildLogger( 'RedisClient' );
-
-const state = {
-  client: null,
-  connectPromise: null
-};
-
-async function connect( url ) {
-  if ( state.client ) {
-    log.warn( 'Closing stale Redis client before reconnecting' );
-    await state.client.quit().catch( quitErr => {
-      log.warn( 'Failed to quit stale Redis client', { error: quitErr.message } );
-    } );
-    state.client = null;
-  }
-
-  const client = createClient( { url, socket: { keepAlive: 15000 } } );
-  try {
-    await client.connect();
-    return state.client = client;
-  } catch ( err ) {
-    await client.quit().catch( () => {} );
-    throw new Error( `Failed to connect to Redis: ${err.message} (${err.code || 'UNKNOWN'})`, { cause: err } );
-  }
-}
+const state = { client: null };
 
 /**
- * Return a connected Redis instance with automatic reconnection.
- *
- * Performs health check on cached client via ping(). If healthy, returns cached
- * instance. Otherwise, closes stale client before creating new connection.
- * Concurrent calls during connection will receive the same pending promise.
- *
- * @returns {Promise<redis.RedisClientType>} Connected Redis client
- * @throws {Error} If REDIS_URL env var is missing
- * @throws {Error} If connection fails (wrapped with context)
+ * Return a connected Redis instance
+ * @returns {redis.RedisClientType}
  */
 export async function getRedisClient() {
-  const url = process.env.REDIS_URL ?? throws( new Error( 'Missing REDIS_URL environment variable' ) );
-
-  const pingResult = await state.client?.ping().catch( err => {
-    log.error( 'Redis ping failed', { error: err.message, code: err.code } );
-    return null;
-  } );
-
-  if ( pingResult === 'PONG' ) {
+  const url = process.env.OUTPUT_REDIS_URL ?? throws( new Error( 'Missing OUTPUT_REDIS_URL environment variable' ) );
+  if ( await state.client?.ping().catch( _ => 0 ) === 'PONG' ) {
     return state.client;
-  }
-
-  if ( state.connectPromise ) {
-    return state.connectPromise;
-  }
-
-  state.connectPromise = connect( url ).finally( () => {
-    state.connectPromise = null;
-  } );
+  };
 
-  return state.connectPromise;
-}
+  const client = createClient( { url, socket: { keepAlive: 15000 } } );
+  await client.connect();
+  return state.client = client;
+};

package/src/tracing/processors/s3/redis_client.spec.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 vi.mock( '#utils', () => ( {
   throws: e => {
@@ -6,14 +6,6 @@ vi.mock( '#utils', () => ( {
   }
 } ) );
 
-const logCalls = { warn: [], error: [] };
-vi.mock( '#logger', () => ( {
-  createChildLogger: () => ( {
-    warn: ( ...args ) => logCalls.warn.push( args ),
-    error: ( ...args ) => logCalls.error.push( args )
-  } )
-} ) );
-
 const createClientImpl = vi.fn();
 vi.mock( 'redis', () => ( { createClient: opts => createClientImpl( opts ) } ) );
 
@@ -25,22 +17,16 @@ async function loadModule() {
 describe( 'tracing/processors/s3/redis_client', () => {
   beforeEach( () => {
     vi.clearAllMocks();
-    delete process.env.REDIS_URL;
-    logCalls.warn = [];
-    logCalls.error = [];
-  } );
-
-  afterEach( () => {
-    vi.useRealTimers();
+    delete process.env.OUTPUT_REDIS_URL;
   } );
 
-  it( 'throws if REDIS_URL is missing', async () => {
+  it( 'throws if OUTPUT_REDIS_URL is missing', async () => {
     const { getRedisClient } = await loadModule();
-    await expect( getRedisClient() ).rejects.toThrow( 'Missing REDIS_URL' );
+    await expect( getRedisClient() ).rejects.toThrow( 'Missing OUTPUT_REDIS_URL' );
   } );
 
   it( 'creates client with url, connects once, then reuses cached when ping is PONG', async () => {
-    process.env.REDIS_URL = 'redis://localhost:6379';
+    process.env.OUTPUT_REDIS_URL = 'redis://localhost:6379';
 
     const pingMock = vi.fn().mockResolvedValue( 'PONG' );
     const connectMock = vi.fn().mockResolvedValue();
@@ -61,121 +47,4 @@ describe( 'tracing/processors/s3/redis_client', () => {
     expect( c1 ).toBe( c2 );
     expect( created[0] ).toMatchObject( { url: 'redis://localhost:6379', socket: { keepAlive: 15000 } } );
   } );
-
-  it( 'closes stale client and reconnects when ping fails', async () => {
-    process.env.REDIS_URL = 'redis://localhost:6379';
-
-    const quitMock = vi.fn().mockResolvedValue();
-    const connectMock = vi.fn().mockResolvedValue();
-    const pingMock = vi.fn()
-      .mockResolvedValueOnce( 'PONG' )
-      .mockRejectedValueOnce( new Error( 'Connection lost' ) )
-      .mockResolvedValueOnce( 'PONG' );
-
-    const created = [];
-    createClientImpl.mockImplementation( opts => {
-      created.push( opts );
-      return { connect: connectMock, ping: pingMock, quit: quitMock };
-    } );
-
-    const { getRedisClient } = await loadModule();
-
-    const c1 = await getRedisClient();
-    const c2 = await getRedisClient();
-    expect( c1 ).toBe( c2 );
-    expect( created ).toHaveLength( 1 );
-
-    const c3 = await getRedisClient();
-    expect( quitMock ).toHaveBeenCalledTimes( 1 );
-    expect( created ).toHaveLength( 2 );
-    expect( c3 ).not.toBe( c1 );
-  } );
-
-  it( 'reconnects successfully even when quit() on stale client rejects', async () => {
-    process.env.REDIS_URL = 'redis://localhost:6379';
-
-    const quitMock = vi.fn().mockRejectedValue( new Error( 'Quit failed' ) );
-    const connectMock = vi.fn().mockResolvedValue();
-    const pingMock = vi.fn()
-      .mockResolvedValueOnce( 'PONG' )
-      .mockRejectedValueOnce( new Error( 'Connection lost' ) )
-      .mockResolvedValueOnce( 'PONG' );
-
-    const created = [];
-    createClientImpl.mockImplementation( opts => {
-      created.push( opts );
-      return { connect: connectMock, ping: pingMock, quit: quitMock };
-    } );
-
-    const { getRedisClient } = await loadModule();
-
-    const c1 = await getRedisClient();
-    const c1again = await getRedisClient();
-    expect( c1 ).toBe( c1again );
-    expect( created ).toHaveLength( 1 );
-
-    const c2 = await getRedisClient();
-    expect( quitMock ).toHaveBeenCalledTimes( 1 );
-    expect( created ).toHaveLength( 2 );
-    expect( c2 ).not.toBe( c1 );
-  } );
-
-  it( 'wraps connect() errors with code and cleans up failed client', async () => {
-    process.env.REDIS_URL = 'redis://localhost:6379';
-
-    const connectErr = new Error( 'Connection refused' );
-    connectErr.code = 'ECONNREFUSED';
-    const connectMock = vi.fn().mockRejectedValue( connectErr );
-    const quitMock = vi.fn().mockResolvedValue();
-
-    createClientImpl.mockImplementation( () => ( {
-      connect: connectMock,
-      quit: quitMock
-    } ) );
-
-    const { getRedisClient } = await loadModule();
-
-    try {
-      await getRedisClient();
-      expect.fail( 'Should have thrown' );
-    } catch ( err ) {
-      expect( err.message ).toBe( 'Failed to connect to Redis: Connection refused (ECONNREFUSED)' );
-      expect( err.cause ).toBe( connectErr );
-    }
-
-    expect( quitMock ).toHaveBeenCalledTimes( 1 );
-  } );
-
-  it( 'logs ping failures with error level', async () => {
-    process.env.REDIS_URL = 'redis://localhost:6379';
-
-    const pingErr = new Error( 'Connection reset' );
-    pingErr.code = 'ECONNRESET';
-    const pingMock = vi.fn()
-      .mockResolvedValueOnce( 'PONG' )
-      .mockRejectedValueOnce( pingErr )
-      .mockResolvedValueOnce( 'PONG' );
-    const connectMock = vi.fn().mockResolvedValue();
-    const quitMock = vi.fn().mockResolvedValue();
-
-    createClientImpl.mockImplementation( () => ( {
-      connect: connectMock,
-      ping: pingMock,
-      quit: quitMock
-    } ) );
-
-    const { getRedisClient } = await loadModule();
-
-    // First call: state.client is null, creates client (no ping)
-    await getRedisClient();
-    // Second call: pings existing client, returns PONG
-    await getRedisClient();
-    // Third call: pings existing client, fails with pingErr, reconnects
-    await getRedisClient();
-
-    expect( logCalls.error ).toContainEqual( [
-      'Redis ping failed',
-      { error: 'Connection reset', code: 'ECONNRESET' }
-    ] );
-  } );
 } );

package/src/tracing/processors/s3/s3_client.js

@@ -12,9 +12,9 @@ const getS3Client = () => {
     return state.s3Client;
   }
 
-  const region = process.env.AWS_REGION ?? throws( new Error( 'Missing AWS_REGION env var' ) );
-  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY ?? throws( new Error( 'Missing AWS_SECRET_ACCESS_KEY env var' ) );
-  const accessKeyId = process.env.AWS_ACCESS_KEY_ID ?? throws( new Error( 'Missing AWS_ACCESS_KEY_ID env var' ) );
+  const region = process.env.OUTPUT_AWS_REGION ?? throws( new Error( 'Missing OUTPUT_AWS_REGION env var' ) );
+  const secretAccessKey = process.env.OUTPUT_AWS_SECRET_ACCESS_KEY ?? throws( new Error( 'Missing OUTPUT_AWS_SECRET_ACCESS_KEY env var' ) );
+  const accessKeyId = process.env.OUTPUT_AWS_ACCESS_KEY_ID ?? throws( new Error( 'Missing OUTPUT_AWS_ACCESS_KEY_ID env var' ) );
 
   return state.s3Client = new S3Client( { region, secretAccessKey, accessKeyId } );
 };
@@ -27,7 +27,7 @@ const getS3Client = () => {
  */
 export const upload = ( { key, content } ) =>
   getS3Client().send( new PutObjectCommand( {
-    Bucket: process.env.TRACE_REMOTE_S3_BUCKET ?? throws( new Error( 'Missing TRACE_REMOTE_S3_BUCKET env var' ) ),
+    Bucket: process.env.OUTPUT_TRACE_REMOTE_S3_BUCKET ?? throws( new Error( 'Missing OUTPUT_TRACE_REMOTE_S3_BUCKET env var' ) ),
     Key: key,
     Body: content
   } ) );

package/src/tracing/processors/s3/s3_client.spec.js

@@ -32,10 +32,10 @@ async function loadModule() {
 describe( 'tracing/processors/s3/s3_client', () => {
   beforeEach( () => {
     vi.clearAllMocks();
-    delete process.env.AWS_REGION;
-    delete process.env.AWS_SECRET_ACCESS_KEY;
-    delete process.env.AWS_ACCESS_KEY_ID;
-    delete process.env.TRACE_REMOTE_S3_BUCKET;
+    delete process.env.OUTPUT_AWS_REGION;
+    delete process.env.OUTPUT_AWS_SECRET_ACCESS_KEY;
+    delete process.env.OUTPUT_AWS_ACCESS_KEY_ID;
+    delete process.env.OUTPUT_TRACE_REMOTE_S3_BUCKET;
   } );
 
   it( 'fails fast when required env vars are missing for client creation', async () => {
@@ -44,10 +44,10 @@ describe( 'tracing/processors/s3/s3_client', () => {
   } );
 
   it( 'creates client once with env and uploads with bucket/key/content', async () => {
-    process.env.AWS_REGION = 'us-east-1';
-    process.env.AWS_SECRET_ACCESS_KEY = 'sek';
-    process.env.AWS_ACCESS_KEY_ID = 'id';
-    process.env.TRACE_REMOTE_S3_BUCKET = 'bucket';
+    process.env.OUTPUT_AWS_REGION = 'us-east-1';
+    process.env.OUTPUT_AWS_SECRET_ACCESS_KEY = 'sek';
+    process.env.OUTPUT_AWS_ACCESS_KEY_ID = 'id';
+    process.env.OUTPUT_TRACE_REMOTE_S3_BUCKET = 'bucket';
 
     const { upload } = await loadModule();
 

package/src/tracing/trace_engine.js

@@ -12,13 +12,13 @@ const log = createChildLogger( 'Tracing' );
 const traceBus = new EventEmitter();
 const processors = [
   {
-    isOn: isStringboolTrue( process.env.TRACE_LOCAL_ON ),
+    isOn: isStringboolTrue( process.env.OUTPUT_TRACE_LOCAL_ON ),
     name: 'LOCAL',
     init: localProcessor.init,
     exec: localProcessor.exec
   },
   {
-    isOn: isStringboolTrue( process.env.TRACE_REMOTE_ON ),
+    isOn: isStringboolTrue( process.env.OUTPUT_TRACE_REMOTE_ON ),
     name: 'REMOTE',
     init: s3Processor.init,
     exec: s3Processor.exec

package/src/tracing/trace_engine.spec.js

@@ -27,14 +27,14 @@ async function loadTraceEngine() {
 describe( 'tracing/trace_engine', () => {
   beforeEach( () => {
     vi.clearAllMocks();
-    delete process.env.TRACE_LOCAL_ON;
-    delete process.env.TRACE_REMOTE_ON;
+    delete process.env.OUTPUT_TRACE_LOCAL_ON;
+    delete process.env.OUTPUT_TRACE_REMOTE_ON;
     storageLoadMock.mockReset();
   } );
 
   it( 'init() starts only enabled processors and attaches listeners', async () => {
-    process.env.TRACE_LOCAL_ON = '1';
-    process.env.TRACE_REMOTE_ON = '0';
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
+    process.env.OUTPUT_TRACE_REMOTE_ON = '0';
     const { init, addEventPhase } = await loadTraceEngine();
 
     await init();
@@ -52,7 +52,7 @@ describe( 'tracing/trace_engine', () => {
   } );
 
   it( 'addEventPhase() emits an entry consumed by processors', async () => {
-    process.env.TRACE_LOCAL_ON = 'on';
+    process.env.OUTPUT_TRACE_LOCAL_ON = 'on';
     const { init, addEventPhase } = await loadTraceEngine();
     await init();
 
@@ -65,7 +65,7 @@ describe( 'tracing/trace_engine', () => {
   } );
 
   it( 'addEventPhaseWithContext() uses storage when available', async () => {
-    process.env.TRACE_LOCAL_ON = 'true';
+    process.env.OUTPUT_TRACE_LOCAL_ON = 'true';
     storageLoadMock.mockReturnValue( { parentId: 'ctx-p', executionContext: { runId: 'r1' } } );
     const { init, addEventPhaseWithContext } = await loadTraceEngine();
     await init();
@@ -80,7 +80,7 @@ describe( 'tracing/trace_engine', () => {
   } );
 
   it( 'addEventPhaseWithContext() is a no-op when storage is absent', async () => {
-    process.env.TRACE_LOCAL_ON = '1';
+    process.env.OUTPUT_TRACE_LOCAL_ON = '1';
     storageLoadMock.mockReturnValue( undefined );
     const { init, addEventPhaseWithContext } = await loadTraceEngine();
     await init();

package/src/worker/configs.js

@@ -1,22 +1,30 @@
 import * as z from 'zod';
+import { isStringboolTrue } from '#utils';
 
 class InvalidEnvVarsErrors extends Error { }
 
+const coalesceEmptyString = v => v === '' ? undefined : v;
+
 const envVarSchema = z.object( {
-  CATALOG_ID: z.string().regex( /^[a-z0-9_.@-]+$/i ),
+  OUTPUT_CATALOG_ID: z.string().regex( /^[a-z0-9_.@-]+$/i ),
   TEMPORAL_ADDRESS: z.string().default( 'localhost:7233' ),
   TEMPORAL_API_KEY: z.string().optional(),
   TEMPORAL_NAMESPACE: z.string().optional().default( 'default' ),
   // Worker concurrency — tune these via env vars to adjust for your workload.
   // Each step (API, LLM, etc.) call is one activity. Lower this to reduce memory pressure.
-  MAX_CONCURRENT_ACTIVITY_TASKS: z.coerce.number().int().positive().default( 40 ),
+  TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 40 ) ),
   // Workflows are lightweight state machines — this can be high.
-  MAX_CONCURRENT_WORKFLOW_TASKS: z.coerce.number().int().positive().default( 200 ),
+  TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_EXECUTIONS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 200 ) ),
   // LRU cache for sticky workflow execution. Lower values free memory faster after surges.
-  MAX_CACHED_WORKFLOWS: z.coerce.number().int().positive().default( 1000 ),
+  TEMPORAL_MAX_CACHED_WORKFLOWS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 1000 ) ),
   // How aggressively the worker pulls tasks from Temporal.
-  MAX_CONCURRENT_ACTIVITY_POLLS: z.coerce.number().int().positive().default( 5 ),
-  MAX_CONCURRENT_WORKFLOW_POLLS: z.coerce.number().int().positive().default( 5 )
+  TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_POLLS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 5 ) ),
+  TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_POLLS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 5 ) ),
+  // Activity configs
+  // How often the worker sends a heartbeat to the Temporal Service during activity execution
+  OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 2 * 60 * 1000 ) ), // 2min
+  // Whether to send activity heartbeats (enabled by default)
+  OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: z.transform( v => v === undefined ? true : isStringboolTrue( v ) )
 } );
 
 const { data: envVars, error } = envVarSchema.safeParse( process.env );
@@ -26,12 +34,13 @@ if ( error ) {
 
 export const address = envVars.TEMPORAL_ADDRESS;
 export const apiKey = envVars.TEMPORAL_API_KEY;
-export const executionTimeout = '1m';
-export const maxActivities = envVars.MAX_CONCURRENT_ACTIVITY_TASKS;
-export const maxWorkflows = envVars.MAX_CONCURRENT_WORKFLOW_TASKS;
-export const maxCachedWorkflows = envVars.MAX_CACHED_WORKFLOWS;
-export const maxActivityPolls = envVars.MAX_CONCURRENT_ACTIVITY_POLLS;
-export const maxWorkflowPolls = envVars.MAX_CONCURRENT_WORKFLOW_POLLS;
+export const maxConcurrentActivityTaskExecutions = envVars.TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS;
+export const maxConcurrentWorkflowTaskExecutions = envVars.TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_EXECUTIONS;
+export const maxCachedWorkflows = envVars.TEMPORAL_MAX_CACHED_WORKFLOWS;
+export const maxConcurrentActivityTaskPolls = envVars.TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_POLLS;
+export const maxConcurrentWorkflowTaskPolls = envVars.TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_POLLS;
 export const namespace = envVars.TEMPORAL_NAMESPACE;
-export const taskQueue = envVars.CATALOG_ID;
-export const catalogId = envVars.CATALOG_ID;
+export const taskQueue = envVars.OUTPUT_CATALOG_ID;
+export const catalogId = envVars.OUTPUT_CATALOG_ID;
+export const activityHeartbeatIntervalMs = envVars.OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS;
+export const activityHeartbeatEnabled = envVars.OUTPUT_ACTIVITY_HEARTBEAT_ENABLED;

package/src/worker/configs.spec.js

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const CONFIG_KEYS = [
+  'OUTPUT_CATALOG_ID',
+  'TEMPORAL_ADDRESS',
+  'TEMPORAL_API_KEY',
+  'TEMPORAL_NAMESPACE',
+  'TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS',
+  'TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_EXECUTIONS',
+  'TEMPORAL_MAX_CACHED_WORKFLOWS',
+  'TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_POLLS',
+  'TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_POLLS',
+  'OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS',
+  'OUTPUT_ACTIVITY_HEARTBEAT_ENABLED'
+];
+
+const setEnv = ( overrides = {} ) => {
+  process.env.OUTPUT_CATALOG_ID = overrides.OUTPUT_CATALOG_ID ?? 'test-catalog';
+  CONFIG_KEYS.forEach( key => {
+    if ( overrides[key] !== undefined ) {
+      process.env[key] = String( overrides[key] );
+    }
+  } );
+};
+
+const clearEnv = () => {
+  CONFIG_KEYS.forEach( key => delete process.env[key] );
+};
+
+async function loadConfigs() {
+  vi.resetModules();
+  return import( './configs.js' );
+}
+
+describe( 'worker/configs', () => {
+  beforeEach( () => clearEnv() );
+  afterEach( () => clearEnv() );
+
+  it( 'throws when OUTPUT_CATALOG_ID is missing', async () => {
+    clearEnv();
+    vi.resetModules();
+
+    await expect( import( './configs.js' ) ).rejects.toThrow();
+  } );
+
+  it( 'throws when OUTPUT_CATALOG_ID does not match regex', async () => {
+    setEnv( { OUTPUT_CATALOG_ID: 'invalid space' } );
+    vi.resetModules();
+
+    await expect( import( './configs.js' ) ).rejects.toThrow();
+  } );
+
+  it( 'uses defaults when only OUTPUT_CATALOG_ID is set', async () => {
+    setEnv();
+    const configs = await loadConfigs();
+
+    expect( configs.address ).toBe( 'localhost:7233' );
+    expect( configs.namespace ).toBe( 'default' );
+    expect( configs.maxConcurrentActivityTaskExecutions ).toBe( 40 );
+    expect( configs.maxConcurrentWorkflowTaskExecutions ).toBe( 200 );
+    expect( configs.maxCachedWorkflows ).toBe( 1000 );
+    expect( configs.maxConcurrentActivityTaskPolls ).toBe( 5 );
+    expect( configs.maxConcurrentWorkflowTaskPolls ).toBe( 5 );
+    expect( configs.activityHeartbeatIntervalMs ).toBe( 2 * 60 * 1000 );
+    expect( configs.activityHeartbeatEnabled ).toBe( true );
+    expect( configs.taskQueue ).toBe( 'test-catalog' );
+    expect( configs.catalogId ).toBe( 'test-catalog' );
+  } );
+
+  it( 'treats empty string for optional number as default (preprocess)', async () => {
+    setEnv( { TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS: '' } );
+    const configs = await loadConfigs();
+
+    expect( configs.maxConcurrentActivityTaskExecutions ).toBe( 40 );
+  } );
+
+  it( 'parses custom numeric env vars', async () => {
+    setEnv( {
+      TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS: '10',
+      TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_EXECUTIONS: '50',
+      TEMPORAL_MAX_CACHED_WORKFLOWS: '500',
+      OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS: '60000'
+    } );
+    const configs = await loadConfigs();
+
+    expect( configs.maxConcurrentActivityTaskExecutions ).toBe( 10 );
+    expect( configs.maxConcurrentWorkflowTaskExecutions ).toBe( 50 );
+    expect( configs.maxCachedWorkflows ).toBe( 500 );
+    expect( configs.activityHeartbeatIntervalMs ).toBe( 60000 );
+  } );
+
+  it( 'throws when optional number is zero or negative', async () => {
+    setEnv( { TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS: '0' } );
+    vi.resetModules();
+
+    await expect( import( './configs.js' ) ).rejects.toThrow();
+  } );
+
+  it( 'OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: "true"|"1"|"on" → true', async () => {
+    for ( const val of [ 'true', '1', 'on' ] ) {
+      setEnv( { OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: val } );
+      const configs = await loadConfigs();
+      expect( configs.activityHeartbeatEnabled ).toBe( true );
+      clearEnv();
+    }
+  } );
+
+  it( 'OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: "false"|other → false, undefined → true', async () => {
+    setEnv( { OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: 'false' } );
+    const configsFalse = await loadConfigs();
+    expect( configsFalse.activityHeartbeatEnabled ).toBe( false );
+
+    setEnv( { OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: '0' } );
+    const configsZero = await loadConfigs();
+    expect( configsZero.activityHeartbeatEnabled ).toBe( false );
+
+    clearEnv();
+    setEnv(); // only OUTPUT_CATALOG_ID; OUTPUT_ACTIVITY_HEARTBEAT_ENABLED absent → default true
+    const configsDefault = await loadConfigs();
+    expect( configsDefault.activityHeartbeatEnabled ).toBe( true );
+  } );
+
+  it( 'parses TEMPORAL_ADDRESS and TEMPORAL_NAMESPACE', async () => {
+    setEnv( { TEMPORAL_ADDRESS: 'temporal:7233', TEMPORAL_NAMESPACE: 'my-ns' } );
+    const configs = await loadConfigs();
+
+    expect( configs.address ).toBe( 'temporal:7233' );
+    expect( configs.namespace ).toBe( 'my-ns' );
+  } );
+} );

package/src/worker/index.js

@@ -1,10 +1,7 @@
 import { Worker, NativeConnection } from '@temporalio/worker';
 import { Client } from '@temporalio/client';
 import { WorkflowIdConflictPolicy } from '@temporalio/common';
-import {
-  address, apiKey, maxActivities, maxWorkflows, maxCachedWorkflows,
-  maxActivityPolls, maxWorkflowPolls, namespace, taskQueue, catalogId
-} from './configs.js';
+import * as configs from './configs.js';
 import { loadActivities, loadWorkflows, createWorkflowsEntryPoint } from './loader.js';
 import { sinks } from './sinks.js';
 import { createCatalog } from './catalog_workflow/index.js';
@@ -20,6 +17,19 @@ const log = createChildLogger( 'Worker' );
 const callerDir = process.argv[2];
 
 ( async () => {
+  const {
+    address,
+    apiKey,
+    namespace,
+    taskQueue,
+    catalogId,
+    maxConcurrentWorkflowTaskExecutions,
+    maxConcurrentActivityTaskExecutions,
+    maxCachedWorkflows,
+    maxConcurrentActivityTaskPolls,
+    maxConcurrentWorkflowTaskPolls
+  } = configs;
+
   log.info( 'Loading workflows...', { callerDir } );
   const workflows = await loadWorkflows( callerDir );
 
@@ -48,11 +58,11 @@ const callerDir = process.argv[2];
     activities,
     sinks,
     interceptors: initInterceptors( { activities } ),
-    maxConcurrentWorkflowTaskExecutions: maxWorkflows,
-    maxConcurrentActivityTaskExecutions: maxActivities,
+    maxConcurrentWorkflowTaskExecutions,
+    maxConcurrentActivityTaskExecutions,
     maxCachedWorkflows,
-    maxConcurrentActivityTaskPolls: maxActivityPolls,
-    maxConcurrentWorkflowTaskPolls: maxWorkflowPolls,
+    maxConcurrentActivityTaskPolls,
+    maxConcurrentWorkflowTaskPolls,
     bundlerOptions: { webpackConfigHook }
   } );
 

package/src/worker/interceptors/activity.js

@@ -3,13 +3,7 @@ import { Storage } from '#async_storage';
 import { addEventStart, addEventEnd, addEventError } from '#tracing';
 import { headersToObject } from '../sandboxed_utils.js';
 import { METADATA_ACCESS_SYMBOL } from '#consts';
-
-// Heartbeat config lives here (not in #consts) because consts.js is bundled into
-// the Temporal workflow sandbox where `process` is not available.
-// Activity interceptors run in the worker context where process.env is safe.
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 2 * 60 * 1000; // 2 minutes
-const HEARTBEAT_INTERVAL_MS = Number( process.env.OUTPUT_HEARTBEAT_INTERVAL_MS ) || DEFAULT_HEARTBEAT_INTERVAL_MS;
-const HEARTBEAT_ENABLED = process.env.OUTPUT_HEARTBEAT_ENABLED !== 'false'; // on by default, set to 'false' to disable
+import { activityHeartbeatEnabled, activityHeartbeatIntervalMs } from '../configs.js';
 
 /*
   This interceptor wraps every activity execution with cross-cutting concerns:
@@ -37,27 +31,24 @@ export class ActivityExecutionInterceptor {
     const { executionContext } = headersToObject( input.headers );
     const { type: kind } = this.activities?.[activityType]?.[METADATA_ACCESS_SYMBOL];
 
-    // --- Tracing: record the start of the activity ---
     const traceArguments = { kind, id: activityId, parentId: workflowId, name: activityType, executionContext };
     addEventStart( { details: input.args[0], ...traceArguments } );
 
-    // --- Heartbeating: signal Temporal periodically that this worker is still alive ---
-    const heartbeatInterval = HEARTBEAT_ENABLED ?
-      setInterval( () => Context.current().heartbeat(), HEARTBEAT_INTERVAL_MS ) :
-      null;
-
+    const intervals = { heartbeat: null };
     try {
-      // --- Execution: run the activity within an AsyncLocalStorage context for nested tracing ---
+      // Sends heartbeat to communicate that activity is still alive
+      intervals.heartbeat = activityHeartbeatEnabled && setInterval( () => Context.current().heartbeat(), activityHeartbeatIntervalMs );
+
       const output = await Storage.runWithContext( async _ => next( input ), { parentId: activityId, executionContext } );
       addEventEnd( { details: output, ...traceArguments } );
       return output;
+
     } catch ( error ) {
       addEventError( { details: error, ...traceArguments } );
       throw error;
+
     } finally {
-      if ( heartbeatInterval ) {
-        clearInterval( heartbeatInterval );
-      }
+      clearInterval( intervals.heartbeat );
     }
   }
 };

package/src/worker/interceptors/activity.spec.js

@@ -43,6 +43,15 @@ vi.mock( '#consts', () => ( {
   }
 } ) );
 
+vi.mock( '../configs.js', () => ( {
+  get activityHeartbeatEnabled() {
+    return process.env.OUTPUT_ACTIVITY_HEARTBEAT_ENABLED !== 'false';
+  },
+  get activityHeartbeatIntervalMs() {
+    return parseInt( process.env.OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS || '120000', 10 );
+  }
+} ) );
+
 const makeActivities = () => ( {
   'myWorkflow#myStep': { [METADATA_ACCESS_SYMBOL]: { type: 'step' } }
 } );
@@ -58,8 +67,8 @@ describe( 'ActivityExecutionInterceptor', () => {
     vi.useFakeTimers();
     vi.resetModules();
     // Default: heartbeat enabled with 50ms interval for fast tests
-    vi.stubEnv( 'OUTPUT_HEARTBEAT_ENABLED', 'true' );
-    vi.stubEnv( 'OUTPUT_HEARTBEAT_INTERVAL_MS', '50' );
+    vi.stubEnv( 'OUTPUT_ACTIVITY_HEARTBEAT_ENABLED', 'true' );
+    vi.stubEnv( 'OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS', '50' );
   } );
 
   afterEach( () => {
@@ -152,8 +161,8 @@ describe( 'ActivityExecutionInterceptor', () => {
     expect( heartbeatMock ).not.toHaveBeenCalled();
   } );
 
-  it( 'does not heartbeat when HEARTBEAT_ENABLED is false', async () => {
-    vi.stubEnv( 'OUTPUT_HEARTBEAT_ENABLED', 'false' );
+  it( 'does not heartbeat when OUTPUT_ACTIVITY_HEARTBEAT_ENABLED is false', async () => {
+    vi.stubEnv( 'OUTPUT_ACTIVITY_HEARTBEAT_ENABLED', 'false' );
     const { ActivityExecutionInterceptor } = await import( './activity.js' );
     const interceptor = new ActivityExecutionInterceptor( makeActivities() );