@outputai/core 0.2.1-next.af8a069.0 → 0.2.1-next.f1502fb.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.2.1-next.af8a069.0",
+  "version": "0.2.1-next.f1502fb.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

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

@@ -2,6 +2,7 @@ import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFile
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'url';
 import buildTraceTree from '../../tools/build_trace_tree.js';
+import { safeFormatJSON } from '../../tools/utils.js';
 import { EOL } from 'node:os';
 
 const __dirname = dirname( fileURLToPath( import.meta.url ) );
@@ -13,12 +14,32 @@ const callerDir = process.argv[2];
 
 const tempTraceFilesDir = join( __dirname, 'temp', 'traces' );
 
-const accumulate = ( { entry, executionContext: { workflowId, startTime } } ) => {
-  const path = join( tempTraceFilesDir, `${startTime}_${workflowId}.trace` );
-  appendFileSync( path, JSON.stringify( entry ) + EOL, 'utf-8' );
-  return readFileSync( path, 'utf-8' ).split( EOL ).slice( 0, -1 ).map( v => JSON.parse( v ) );
-};
+/**
+ * Builds the temp file path to accumulate trace entries
+ *
+ * @param {object} executionContext - The execution context around a given trace entry
+ * @returns {string}
+ */
+const createTempFilePath = ( { workflowId, startTime } ) => join( tempTraceFilesDir, `${startTime}_${workflowId}.trace` );
+
+/**
+ * Adds an trace entry to the accumulation file
+ * @param {object} entry - The trace entry
+ * @param {string} path - Accumulation file path
+ */
+const addEntry = ( entry, path ) => appendFileSync( path, JSON.stringify( entry ) + EOL, 'utf-8' );
 
+/**
+ * Reads the accumulation file and returns all the entries, each serialized to JSON
+ * @param {string} path - Accumulation file path
+ * @returns {object[]} Trace entries
+ */
+const getEntries = path => readFileSync( path, 'utf-8' ).split( EOL ).slice( 0, -1 ).map( v => JSON.parse( v ) );
+
+/**
+ * Deletes old accumulation files
+ * @param {number} [threshold] Timestamp in ms epoch. All files below this date are considered old
+ */
 const cleanupOldTempFiles = ( threshold = Date.now() - tempFilesTTL ) =>
   readdirSync( tempTraceFilesDir )
     .filter( f => +f.split( '_' )[0] < threshold )
@@ -79,7 +100,8 @@ export const init = () => {
 /**
  * Execute this processor:
  *
- * Persist a trace tree file to local file system, updating upon each new entry
+ * Append each trace entry to a temp file; when the root workflow ends (non-start phase on the
+ * workflow id) or any entry is an error phase, build the trace tree and write the JSON file once.
  *
  * @param {object} args
  * @param {object} entry - Trace event phase
@@ -88,12 +110,22 @@ export const init = () => {
  */
 export const exec = ( { entry, executionContext } ) => {
   const { workflowId, workflowName, startTime } = executionContext;
-  const content = buildTraceTree( accumulate( { entry, executionContext } ) );
+  const tempFilePath = createTempFilePath( executionContext );
+  addEntry( entry, tempFilePath );
+
+  const isRootWorkflowEnd = entry.id === workflowId && entry.phase !== 'start';
+  const isError = entry.phase === 'error';
+
+  if ( !isRootWorkflowEnd && !isError ) {
+    return;
+  }
+
+  const content = buildTraceTree( getEntries( tempFilePath ) );
   const dir = resolveIOPath( workflowName );
   const path = join( dir, buildTraceFilename( { startTime, workflowId } ) );
 
   mkdirSync( dir, { recursive: true } );
-  writeFileSync( path, JSON.stringify( content, undefined, 2 ) + EOL, 'utf-8' );
+  writeFileSync( path, safeFormatJSON( content ) + EOL, 'utf-8' );
 };
 
 /**

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

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { EOL } from 'node:os';
 
 // In-memory fs mock store
 const store = { files: new Map() };
@@ -24,12 +25,17 @@ vi.mock( 'node:fs', () => ( {
 const buildTraceTreeMock = vi.fn( entries => ( { count: entries.length } ) );
 vi.mock( '../../tools/build_trace_tree.js', () => ( { default: buildTraceTreeMock } ) );
 
+/** Flush happens when root id matches workflowId and phase is not start, or when phase is error. */
+const rootStart = ( workflowId, ts ) => ( { id: workflowId, phase: 'start', timestamp: ts } );
+const rootEnd = ( workflowId, ts ) => ( { id: workflowId, phase: 'end', timestamp: ts } );
+const childTick = ( id, ts ) => ( { id, phase: 'tick', timestamp: ts } );
+
 describe( 'tracing/processors/local', () => {
   beforeEach( () => {
     vi.clearAllMocks();
     store.files.clear();
     process.argv[2] = '/tmp/project';
-    delete process.env.OUTPUT_TRACE_HOST_PATH; // Clear OUTPUT_TRACE_HOST_PATH for clean tests
+    delete process.env.OUTPUT_TRACE_HOST_PATH;
   } );
 
   it( 'init(): creates temp dir and cleans up old files', async () => {
@@ -40,34 +46,63 @@ describe( 'tracing/processors/local', () => {
 
     init();
 
-    // Should create temp dir relative to module location using __dirname
     expect( mkdirSyncMock ).toHaveBeenCalledWith( expect.stringMatching( /temp\/traces$/ ), { recursive: true } );
     expect( rmSyncMock ).toHaveBeenCalledTimes( 1 );
   } );
 
-  it( 'exec(): accumulates entries and writes aggregated tree', async () => {
+  it( 'exec(): appends each entry and writes aggregated tree once on root workflow end', async () => {
     const { exec, init } = await import( './index.js' );
     init();
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
-    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
 
-    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
-    exec( { ...ctx, entry: { name: 'A', phase: 'tick', timestamp: startTime + 1 } } );
-    exec( { ...ctx, entry: { name: 'A', phase: 'end', timestamp: startTime + 2 } } );
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: childTick( 'child-1', startTime + 1 ) } );
+    exec( { ...ctx, entry: rootEnd( workflowId, startTime + 2 ) } );
 
-    // buildTraceTree called with 1, 2, 3 entries respectively
-    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 3 );
-    expect( buildTraceTreeMock.mock.calls.at( -1 )[0].length ).toBe( 3 );
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 1 );
+    expect( buildTraceTreeMock.mock.calls[0][0] ).toHaveLength( 3 );
 
-    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 3 );
-    const [ writtenPath, content ] = writeFileSyncMock.mock.calls.at( -1 );
-    // Changed: Now uses process.cwd() + '/logs' fallback when OUTPUT_TRACE_HOST_PATH not set
-    expect( writtenPath ).toMatch( /\/runs\/WF\// );
+    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
+    const [ writtenPath, content ] = writeFileSyncMock.mock.calls[0];
+    expect( writtenPath ).toMatch( /\/tmp\/project\/logs\/runs\/WF\// );
     expect( JSON.parse( content.trim() ).count ).toBe( 3 );
   } );
 
-  it( 'getDestination(): returns absolute path', async () => {
+  it( 'exec(): does not build or write on non-flush entries', async () => {
+    const { exec, init } = await import( './index.js' );
+    init();
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
+
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: childTick( 'child-1', startTime + 1 ) } );
+
+    expect( buildTraceTreeMock ).not.toHaveBeenCalled();
+    expect( writeFileSyncMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'exec(): flushes on error phase before root end', async () => {
+    const { exec, init } = await import( './index.js' );
+    init();
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
+
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: { id: 'step-1', phase: 'error', timestamp: startTime + 1 } } );
+
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 1 );
+    expect( buildTraceTreeMock.mock.calls[0][0] ).toHaveLength( 2 );
+    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'getDestination(): returns absolute path under callerDir logs', async () => {
     const { getDestination } = await import( './index.js' );
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
@@ -76,36 +111,36 @@ describe( 'tracing/processors/local', () => {
 
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Should return an absolute path
-    expect( destination ).toMatch( /^\/|^[A-Z]:\\/i ); // Starting with / or Windows drive letter
-    expect( destination ).toContain( '/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
+    expect( destination ).toMatch( /^\/|^[A-Z]:\\/i );
+    expect( destination ).toBe(
+      '/tmp/project/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json'
+    );
   } );
 
-  it( 'exec(): writes to container path regardless of OUTPUT_TRACE_HOST_PATH', async () => {
+  it( 'exec(): writes under process.argv[2] logs even when OUTPUT_TRACE_HOST_PATH is set', async () => {
     const { exec, init } = await import( './index.js' );
 
-    // Set OUTPUT_TRACE_HOST_PATH to simulate Docker environment
     process.env.OUTPUT_TRACE_HOST_PATH = '/host/path/logs';
 
     init();
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
-    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
 
-    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: rootEnd( workflowId, startTime + 1 ) } );
 
     expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
-    const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
+    const [ writtenPath ] = writeFileSyncMock.mock.calls[0];
 
-    // 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\// );
+    expect( writtenPath ).toMatch( /\/tmp\/project\/logs\/runs\/WF\// );
   } );
 
   it( 'getDestination(): returns OUTPUT_TRACE_HOST_PATH when set', async () => {
     const { getDestination } = await import( './index.js' );
 
-    // 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' );
@@ -114,14 +149,12 @@ describe( 'tracing/processors/local', () => {
 
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // 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 OUTPUT_TRACE_HOST_PATH to simulate Docker environment
     process.env.OUTPUT_TRACE_HOST_PATH = '/Users/ben/project/logs';
 
     init();
@@ -131,19 +164,16 @@ describe( 'tracing/processors/local', () => {
     const workflowName = 'test-workflow';
     const ctx = { executionContext: { workflowId, workflowName, startTime } };
 
-    // Execute to write file
-    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: rootEnd( workflowId, startTime + 1 ) } );
 
-    // Get destination for reporting
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Verify write path is local
-    const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
+    const [ writtenPath, payload ] = writeFileSyncMock.mock.calls[0];
     expect( writtenPath ).not.toContain( '/Users/ben/project' );
-    expect( writtenPath ).toMatch( /logs\/runs\/test-workflow\// );
+    expect( writtenPath ).toMatch( /\/tmp\/project\/logs\/runs\/test-workflow\// );
+    expect( payload.endsWith( EOL ) ).toBe( true );
 
-    // 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

@@ -4,6 +4,7 @@ import buildTraceTree from '../../tools/build_trace_tree.js';
 import { EOL } from 'node:os';
 import { loadEnv, getVars } from './configs.js';
 import { createChildLogger } from '#logger';
+import { safeFormatJSON } from '../../tools/utils.js';
 
 const log = createChildLogger( 'S3 Processor' );
 
@@ -97,7 +98,7 @@ export const exec = async ( { entry, executionContext } ) => {
   }
   await upload( {
     key: getS3Key( { workflowId, workflowName, startTime } ),
-    content: JSON.stringify( content, undefined, 2 ) + EOL
+    content: safeFormatJSON( content ) + EOL
   } );
   await bustEntries( cacheKey );
 };

package/src/tracing/tools/utils.js

@@ -19,3 +19,31 @@ export const serializeError = error =>
     message: error.message,
     stack: error.stack
   };
+
+/**
+ * Tries to stringify an object to an indented JSON string.
+ * If its byte size is bigger than threshold returns a plain JSON string without formatting.
+ *
+ * @param {object|array} content
+ * @param {*} [threshold] - The max allowed size to try to stringify with formatting (in bytes). Default is 50mb
+ * @returns {string} String representation of the object
+ */
+export const safeFormatJSON = ( content, threshold = 50 * 1024 * 1024 /* 50mb */ ) => {
+  const plainString = JSON.stringify( content );
+  const plainStringSize = Buffer.byteLength( plainString, 'utf8' );
+
+  if ( plainStringSize > threshold ) {
+    return plainString;
+  }
+  try {
+    return JSON.stringify( content, undefined, 2 );
+  } catch ( error ) {
+    // Only handles this specific error because other common parsing errors like:
+    // "TypeError: cyclic object value" and "RangeError: Maximum call stack size exceeded"
+    // would have been thrown on the first parsing.
+    if ( error instanceof RangeError && error.message === 'Invalid string length' ) {
+      return plainString;
+    }
+    throw error;
+  }
+};

package/src/tracing/tools/utils.spec.js

@@ -1,5 +1,15 @@
-import { describe, it, expect } from 'vitest';
-import { serializeError } from './utils.js';
+import { describe, it, expect, vi } from 'vitest';
+import { safeFormatJSON, serializeError } from './utils.js';
+
+const isPrettyStringifyCall = args => args.length >= 3 && args[2] === 2;
+
+/** @param {number} targetBytes UTF-8 size of compact JSON.stringify( { a: "<xs>" } ) */
+const objectWithCompactByteLength = targetBytes => {
+  const sample = { a: '' };
+  const overhead = Buffer.byteLength( JSON.stringify( sample ), 'utf8' );
+  const repeat = Math.max( 0, targetBytes - overhead );
+  return { a: 'x'.repeat( repeat ) };
+};
 
 describe( 'tracing/utils', () => {
   it( 'serializeError unwraps causes and keeps message/stack', () => {
@@ -11,4 +21,126 @@ describe( 'tracing/utils', () => {
     expect( out.message ).toBe( 'inner' );
     expect( typeof out.stack ).toBe( 'string' );
   } );
+
+  describe( 'safeFormatJSON', () => {
+    it( 'formats small objects with indentation when under threshold', () => {
+      const content = { a: 1, b: [ 2, 3 ] };
+      const out = safeFormatJSON( content, 10_000 );
+
+      expect( out ).toContain( '\n' );
+      expect( out ).toMatch( /^\{\n/ );
+      expect( JSON.parse( out ) ).toEqual( content );
+    } );
+
+    it( 'formats small arrays with indentation when under threshold', () => {
+      const content = [ 1, { nested: true } ];
+      const out = safeFormatJSON( content, 10_000 );
+
+      expect( out ).toContain( '\n' );
+      expect( out.trimStart() ).toMatch( /^\[/ );
+      expect( JSON.parse( out ) ).toEqual( content );
+    } );
+
+    it( 'returns compact JSON when compact UTF-8 size is strictly greater than threshold', () => {
+      const content = objectWithCompactByteLength( 40 );
+      const compact = JSON.stringify( content );
+      expect( Buffer.byteLength( compact, 'utf8' ) ).toBe( 40 );
+
+      const out = safeFormatJSON( content, 39 );
+      expect( out ).toBe( compact );
+      expect( out ).not.toContain( '\n  ' );
+      expect( JSON.parse( out ) ).toEqual( content );
+    } );
+
+    it( 'uses pretty JSON when compact UTF-8 size equals threshold', () => {
+      const content = objectWithCompactByteLength( 40 );
+      const compact = JSON.stringify( content );
+      expect( Buffer.byteLength( compact, 'utf8' ) ).toBe( 40 );
+
+      const out = safeFormatJSON( content, 40 );
+      expect( out ).not.toBe( compact );
+      expect( out ).toContain( '\n' );
+      expect( JSON.parse( out ) ).toEqual( content );
+    } );
+
+    it( 'uses UTF-8 byte length for threshold, not JavaScript string length', () => {
+      const content = { label: 'éclair' };
+      const compact = JSON.stringify( content );
+      expect( compact.length ).toBeLessThan( Buffer.byteLength( compact, 'utf8' ) );
+
+      const bytes = Buffer.byteLength( compact, 'utf8' );
+      const outCompact = safeFormatJSON( content, bytes - 1 );
+      expect( outCompact ).toBe( compact );
+
+      const outPretty = safeFormatJSON( content, bytes + 100 );
+      expect( outPretty ).toContain( '\n' );
+      expect( JSON.parse( outPretty ) ).toEqual( content );
+    } );
+
+    it( 'round-trips empty object and primitives for both branches', () => {
+      const tiny = {};
+      const pretty = safeFormatJSON( tiny, 100 );
+      expect( JSON.parse( pretty ) ).toEqual( tiny );
+
+      const forcedCompact = safeFormatJSON( tiny, 0 );
+      expect( JSON.parse( forcedCompact ) ).toEqual( tiny );
+    } );
+
+    it( 'returns compact JSON when pretty stringify throws Invalid string length', () => {
+      const content = { a: 1 };
+      const compact = JSON.stringify( content );
+      const origStringify = JSON.stringify.bind( JSON );
+
+      const spy = vi.spyOn( JSON, 'stringify' ).mockImplementation( ( ...args ) => {
+        if ( isPrettyStringifyCall( args ) ) {
+          throw new RangeError( 'Invalid string length' );
+        }
+        return origStringify( ...args );
+      } );
+
+      try {
+        const out = safeFormatJSON( content, 10_000 );
+        expect( out ).toBe( compact );
+        expect( JSON.parse( out ) ).toEqual( content );
+      } finally {
+        spy.mockRestore();
+      }
+    } );
+
+    it( 'rethrows RangeError when message is not Invalid string length', () => {
+      const content = { a: 1 };
+      const origStringify = JSON.stringify.bind( JSON );
+
+      const spy = vi.spyOn( JSON, 'stringify' ).mockImplementation( ( ...args ) => {
+        if ( isPrettyStringifyCall( args ) ) {
+          throw new RangeError( 'not the string length error' );
+        }
+        return origStringify( ...args );
+      } );
+
+      try {
+        expect( () => safeFormatJSON( content, 10_000 ) ).toThrow( RangeError );
+      } finally {
+        spy.mockRestore();
+      }
+    } );
+
+    it( 'rethrows non-RangeError from pretty stringify', () => {
+      const content = { a: 1 };
+      const origStringify = JSON.stringify.bind( JSON );
+
+      const spy = vi.spyOn( JSON, 'stringify' ).mockImplementation( ( ...args ) => {
+        if ( isPrettyStringifyCall( args ) ) {
+          throw new TypeError( 'cyclic structure' );
+        }
+        return origStringify( ...args );
+      } );
+
+      try {
+        expect( () => safeFormatJSON( content, 10_000 ) ).toThrow( TypeError );
+      } finally {
+        spy.mockRestore();
+      }
+    } );
+  } );
 } );

package/src/worker/configs.js

@@ -26,7 +26,14 @@ const envVarSchema = z.object( {
   // Whether to send activity heartbeats (enabled by default)
   OUTPUT_ACTIVITY_HEARTBEAT_ENABLED: z.transform( v => v === undefined ? true : isStringboolTrue( v ) ),
   // Time to allow for hooks to flush before shutdown
-  OUTPUT_PROCESS_FAILURE_SHUTDOWN_DELAY: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 3000 ) )
+  OUTPUT_PROCESS_FAILURE_SHUTDOWN_DELAY: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 3000 ) ),
+  // HTTP CONNECT proxy for Temporal gRPC connections (e.g. "proxy-host:8080").
+  // Must be a bare host:port — no scheme (Temporal's native HTTP CONNECT
+  // option is not a URL).
+  TEMPORAL_GRPC_PROXY: z.string().optional().refine(
+    v => !v || !v.includes( '://' ),
+    'TEMPORAL_GRPC_PROXY must be host:port without a scheme (e.g. "proxy:8080", not "http://proxy:8080")'
+  )
 } );
 
 const { data: envVars, error } = envVarSchema.safeParse( process.env );
@@ -47,3 +54,4 @@ export const catalogId = envVars.OUTPUT_CATALOG_ID;
 export const activityHeartbeatIntervalMs = envVars.OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS;
 export const activityHeartbeatEnabled = envVars.OUTPUT_ACTIVITY_HEARTBEAT_ENABLED;
 export const processFailureShutdownDelay = envVars.OUTPUT_PROCESS_FAILURE_SHUTDOWN_DELAY;
+export const grpcProxy = envVars.TEMPORAL_GRPC_PROXY;

package/src/worker/index.js

@@ -9,6 +9,7 @@ import { initInterceptors } from './interceptors.js';
 import { createChildLogger } from '#logger';
 import { registerShutdown } from './shutdown.js';
 import { startCatalog } from './start_catalog.js';
+import { bootstrapFetchProxy } from './proxy.js';
 import { messageBus } from '#bus';
 import './log_hooks.js';
 import { BusEventType } from '#consts';
@@ -24,6 +25,7 @@ const callerDir = process.argv[2];
     apiKey,
     namespace,
     taskQueue,
+    grpcProxy,
     maxConcurrentWorkflowTaskExecutions,
     maxConcurrentActivityTaskExecutions,
     maxCachedWorkflows,
@@ -41,6 +43,7 @@ const callerDir = process.argv[2];
   const activities = await loadActivities( callerDir, workflows );
 
   messageBus.emit( BusEventType.WORKER_BEFORE_START );
+  bootstrapFetchProxy();
 
   log.info( 'Creating worker entry point...' );
   const workflowsPath = createWorkflowsEntryPoint( workflows );
@@ -52,8 +55,11 @@ const callerDir = process.argv[2];
   const catalog = createCatalog( { workflows, activities } );
 
   log.info( 'Connecting Temporal...' );
-  // Enable TLS when connecting to remote Temporal (API key present)
-  const connection = await NativeConnection.connect( { address, tls: Boolean( apiKey ), apiKey } );
+  const proxy = grpcProxy ? { type: 'http-connect', targetHost: grpcProxy } : undefined;
+  if ( proxy ) {
+    log.info( 'Using gRPC proxy', { targetHost: grpcProxy } );
+  }
+  const connection = await NativeConnection.connect( { address, tls: Boolean( apiKey ), apiKey, proxy } );
 
   log.info( 'Creating worker...' );
   const worker = await Worker.create( {

package/src/worker/index.spec.js

@@ -16,6 +16,7 @@ const configValues = {
   namespace: 'default',
   taskQueue: 'test-queue',
   catalogId: 'test-catalog',
+  grpcProxy: undefined,
   maxConcurrentWorkflowTaskExecutions: 200,
   maxConcurrentActivityTaskExecutions: 40,
   maxCachedWorkflows: 1000,
@@ -52,6 +53,9 @@ vi.mock( './interceptors.js', () => ( { initInterceptors: initInterceptorsMock }
 const startCatalogMock = vi.fn().mockResolvedValue( undefined );
 vi.mock( './start_catalog.js', () => ( { startCatalog: startCatalogMock } ) );
 
+const bootstrapFetchProxyMock = vi.fn();
+vi.mock( './proxy.js', () => ( { bootstrapFetchProxy: bootstrapFetchProxyMock } ) );
+
 const registerShutdownMock = vi.fn();
 vi.mock( './shutdown.js', () => ( { registerShutdown: registerShutdownMock } ) );
 
@@ -101,10 +105,12 @@ describe( 'worker/index', () => {
     expect( createWorkflowsEntryPointMock ).toHaveBeenCalledWith( [] );
     expect( initTracing ).toHaveBeenCalled();
     expect( createCatalogMock ).toHaveBeenCalledWith( { workflows: [], activities: {} } );
+    expect( bootstrapFetchProxyMock ).toHaveBeenCalled();
     expect( NativeConnection.connect ).toHaveBeenCalledWith( {
       address: configValues.address,
       tls: false,
-      apiKey: undefined
+      apiKey: undefined,
+      proxy: undefined
     } );
     expect( Worker.create ).toHaveBeenCalledWith( expect.objectContaining( {
       namespace: configValues.namespace,

package/src/worker/proxy.js

@@ -0,0 +1,32 @@
+import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Proxy' );
+
+/**
+ * Routes all `fetch()` calls (including those inside Temporal activities)
+ * through an HTTP/HTTPS proxy when standard proxy env vars are set
+ * (`HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY`, `http_proxy`). No-op when
+ * none are set. Invalid URLs are logged and skipped so the worker keeps
+ * running.
+ *
+ * Call once at worker startup, before any network activity.
+ */
+export const bootstrapFetchProxy = () => {
+  const proxyUrl = process.env.HTTPS_PROXY || process.env.https_proxy ||
+    process.env.HTTP_PROXY || process.env.http_proxy;
+
+  if ( !proxyUrl ) {
+    return;
+  }
+
+  try {
+    new URL( proxyUrl );
+  } catch {
+    log.warn( 'Ignoring invalid proxy URL', { proxyUrl } );
+    return;
+  }
+
+  log.info( 'Routing fetch() through HTTP proxy', { proxyUrl } );
+  setGlobalDispatcher( new EnvHttpProxyAgent() );
+};

package/src/worker/proxy.spec.js

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const mockSetGlobalDispatcher = vi.fn();
+const MockEnvHttpProxyAgent = vi.fn();
+
+vi.mock( 'undici', () => ( {
+  EnvHttpProxyAgent: MockEnvHttpProxyAgent,
+  setGlobalDispatcher: mockSetGlobalDispatcher
+} ) );
+
+vi.mock( '#logger', () => ( {
+  createChildLogger: () => ( { info: vi.fn(), warn: vi.fn(), error: vi.fn() } )
+} ) );
+
+describe( 'worker/proxy', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach( () => {
+    vi.clearAllMocks();
+    delete process.env.HTTPS_PROXY;
+    delete process.env.https_proxy;
+    delete process.env.HTTP_PROXY;
+    delete process.env.http_proxy;
+  } );
+
+  afterEach( () => {
+    process.env = { ...originalEnv };
+  } );
+
+  it( 'does nothing when no proxy env vars are set', async () => {
+    const { bootstrapFetchProxy } = await import( './proxy.js' );
+    bootstrapFetchProxy();
+
+    expect( mockSetGlobalDispatcher ).not.toHaveBeenCalled();
+  } );
+
+  it( 'sets global dispatcher when HTTPS_PROXY is set', async () => {
+    process.env.HTTPS_PROXY = 'http://proxy:8080';
+    const { bootstrapFetchProxy } = await import( './proxy.js' );
+    bootstrapFetchProxy();
+
+    expect( MockEnvHttpProxyAgent ).toHaveBeenCalled();
+    expect( mockSetGlobalDispatcher ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'sets global dispatcher when HTTP_PROXY is set', async () => {
+    process.env.HTTP_PROXY = 'http://proxy:8080';
+    const { bootstrapFetchProxy } = await import( './proxy.js' );
+    bootstrapFetchProxy();
+
+    expect( MockEnvHttpProxyAgent ).toHaveBeenCalled();
+    expect( mockSetGlobalDispatcher ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'prefers HTTPS_PROXY over HTTP_PROXY for detection', async () => {
+    process.env.HTTPS_PROXY = 'http://secure-proxy:8080';
+    process.env.HTTP_PROXY = 'http://plain-proxy:8080';
+    const { bootstrapFetchProxy } = await import( './proxy.js' );
+    bootstrapFetchProxy();
+
+    expect( mockSetGlobalDispatcher ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'does not set global dispatcher when proxy URL is malformed', async () => {
+    process.env.HTTPS_PROXY = 'not a url';
+    const { bootstrapFetchProxy } = await import( './proxy.js' );
+    bootstrapFetchProxy();
+
+    expect( mockSetGlobalDispatcher ).not.toHaveBeenCalled();
+  } );
+} );