@outputai/core 0.15.1-dev.46e7530.0 → 0.15.1-next.2032ff6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.15.1-dev.46e7530.0",
+  "version": "0.15.1-next.2032ff6.0",
   "description": "The core module of the output framework",
   "type": "module",
   "engines": {
@@ -30,6 +30,10 @@
     "./credentials": {
       "types": "./dist/credentials/index.d.ts",
       "import": "./dist/credentials/index.js"
+    },
+    "./http": {
+      "types": "./src/http/index.d.ts",
+      "import": "./src/http/index.js"
     }
   },
   "files": [
@@ -63,15 +67,18 @@
     "json-stream-stringify": "3.1.7",
     "redis": "5.12.1",
     "stacktrace-parser": "0.1.11",
-    "undici": "8.11.0",
     "winston": "3.19.0"
   },
   "peerDependencies": {
-    "zod": ">=4.3 <5"
+    "zod": ">=4.3 <5",
+    "ky": ">=2 <3",
+    "undici": ">=8 <9"
   },
   "devDependencies": {
     "@types/js-yaml": "4.0.9",
-    "zod": "4.6.5"
+    "zod": "4.6.5",
+    "ky": "2.0.2",
+    "undici": "8.11.0"
   },
   "license": "Apache-2.0",
   "publishConfig": {
@@ -83,6 +90,7 @@
     "#credentials/*": "./dist/credentials/*.js",
     "#errors": "./src/errors.js",
     "#logger": "./src/logger/index.js",
+    "#runtime_logger": "./src/interface/logger.js",
     "#hooks/*": "./src/hooks/*.js",
     "#helpers/*": "./src/helpers/*.js",
     "#tracing": "./src/tracing/internal_interface.js",

package/src/helpers/fetch.js

@@ -1,19 +1,31 @@
 import { FatalError } from '#errors';
 import { redactHeaders } from './redact.js';
 
+const jsonMatcher = /^application\/(?:json|[^;\s]+?\+json)(?:\s*;.*)?$/i;
+const textMatcher = /^(?:text\/|application\/(?:xml|[^;\s]+?\+xml|x-www-form-urlencoded|javascript)(?:\s*;|$))/i;
+
 /**
- * Consume the body of a Response according it its content-type and returns it
+ * Consume the body of a Response according it its content-type and returns it:
+ * - JSON content-type: parsed JSON, or the raw text if the body is empty or not valid JSON
+ * - text-like content-type: the text as-is
+ * - anything else: the body bytes as a base64 string
  * @param {Response} response
- * @returns {string|object|undefined|null} The response body content
+ * @returns {string|object|null} The response body content
  */
-const consumeBody = async response => {
-  const headers = Object.fromEntries( response.headers ) ?? {};
-  const contentType = ( headers['content-type'] ?? '' ).trim().toLowerCase();
-  const jsonMatcher = /^application\/(?:json|[^;\s]+?\+json)(?:\s*;.*)?$/i;
+export const consumeBody = async response => {
+  const contentType = ( response.headers.get( 'content-type' ) ?? '' ).trim();
   if ( jsonMatcher.test( contentType ) ) {
-    return response.json();
+    const text = await response.text();
+    if ( text.length === 0 ) {
+      return text;
+    }
+    try {
+      return JSON.parse( text );
+    } catch {
+      return text;
+    }
   }
-  if ( contentType.startsWith( 'text/' ) ) {
+  if ( textMatcher.test( contentType ) ) {
     return response.text();
   }
   return response.arrayBuffer().then( buf => Buffer.from( buf ).toString( 'base64' ) );
@@ -33,7 +45,7 @@ export const serializeResponse = async ( response, { includeHeaders = false, inc
   status: response.status,
   statusText: response.statusText,
   ok: response.ok,
-  ...( includeHeaders && { headers: redactHeaders( Object.fromEntries( response.headers ) ) } ),
+  ...( includeHeaders && { headers: redactHeaders( response.headers ) } ),
   ...( includeBody && { body: await consumeBody( response ) } )
 } );
 

package/src/helpers/redact.js

@@ -43,7 +43,8 @@ export const redactHeaders = headers => {
     wordEndMatcher( 'key' )
   ];
 
-  return Object.entries( headers ).reduce( ( redacted, [ key, value ] ) => {
+  const plainHeaders = Object.fromEntries( headers );
+  return Object.entries( plainHeaders ).reduce( ( redacted, [ key, value ] ) => {
     const lowKey = key.toLowerCase();
     const isSensitive = !ignoreHeaders.has( lowKey ) && sensitiveHeadersPatterns.some( rx => rx.test( lowKey ) );
     return Object.assign( redacted, { [key]: isSensitive ? '[REDACTED]' : value } );

package/src/http/config.js

@@ -0,0 +1,10 @@
+/**
+ * Configuration for HTTP client behavior
+ */
+export const config = {
+  /**
+   * Whether to log verbose HTTP information (headers and bodies)
+   * Controlled by OUTPUT_TRACE_HTTP_VERBOSE environment variable
+   */
+  logVerbose: [ '1', 'true' ].includes( process.env.OUTPUT_TRACE_HTTP_VERBOSE )
+};

package/src/http/cost.d.ts

@@ -0,0 +1,20 @@
+import type { KyResponse } from 'ky';
+import { Attribute } from '#trace_attribute';
+
+/** Trace attribute (`http:request:cost`) holding the cost attached to an HTTP request with `addRequestCost` */
+export declare class HTTPRequestCost extends Attribute.BaseAttribute {
+  static TYPE: 'http:request:cost';
+  type: typeof HTTPRequestCost.TYPE;
+  url: string;
+  requestId: string;
+  total: number;
+  constructor( url: string, requestId: string, total: number );
+}
+
+/**
+ * Attach cost information to the trace of an HTTP Request using the response
+ *
+ * @param response - The response of the HTTP Request to attach the information
+ * @param value - The price of the HTTP request
+ */
+export declare function addRequestCost( response: KyResponse | Response, value: number ): void;

package/src/http/cost.js

@@ -0,0 +1,41 @@
+import { stepEventBus } from '#bus';
+import { requestIdSymbol } from './request_tag.js';
+import { Logger } from '#runtime_logger';
+import { addEventActionWithContext, EventAction } from '#tracing';
+import { BaseAttribute } from '#trace_attribute';
+
+export class HTTPRequestCost extends BaseAttribute {
+  static TYPE = 'http:request:cost';
+  url;
+  requestId;
+  total = 0;
+
+  constructor( url, requestId, total ) {
+    super( HTTPRequestCost.TYPE );
+    this.url = url;
+    this.requestId = requestId;
+    this.total = total;
+  }
+}
+
+/**
+ * Attach cost information to the trace of an HTTP Request using the response
+ *
+ * @param {Response} response - The response of the HTTP Request to attach the information
+ * @param {number} value - The price of the HTTP request
+ * @returns {void}
+ */
+export const addRequestCost = ( response, value ) => {
+  const eventId = Reflect.get( response, requestIdSymbol );
+  if ( !eventId ) {
+    Logger.warn(
+      'addRequestCost(): The "response" argument did not originate from @outputai/core/http, no costs were added.',
+      { namespace: 'HTTP' }
+    );
+    return;
+  }
+
+  const attribute = new HTTPRequestCost( response.url, eventId, value );
+  addEventActionWithContext( EventAction.ADD_ATTR, { id: eventId, details: attribute } );
+  stepEventBus.emit( 'sdk:cost:http:request', attribute );
+};

package/src/http/fetch/events.js

@@ -0,0 +1,10 @@
+import { stepEventBus } from '#bus';
+
+export const emitError = ( { requestId, method, url, status, durationMs } ) =>
+  stepEventBus.emit( 'sdk:http:request', { requestId, method, url, status, durationMs, outcome: 'error' } );
+
+export const emitSuccess = ( { requestId, method, url, status, durationMs } ) =>
+  stepEventBus.emit( 'sdk:http:request', { requestId, method, url, status, durationMs, outcome: 'success' } );
+
+export const emitFailure = ( { requestId, method, url, durationMs } ) =>
+  stepEventBus.emit( 'sdk:http:request', { requestId, method, url, status: undefined, durationMs, outcome: 'failure' } );

package/src/http/fetch/index.d.ts

@@ -0,0 +1,26 @@
+import type * as undici from 'undici';
+
+type NodeRequestInfo = string | URL | globalThis.Request;
+type NodeRequestInit = globalThis.RequestInit & Pick<undici.RequestInit, 'dispatcher'>;
+
+type OutputFetch = {
+  ( input: NodeRequestInfo, init?: NodeRequestInit ): Promise<Response>;
+  ( input: undici.RequestInfo, init?: undici.RequestInit ): Promise<Response>;
+};
+
+/**
+ * A fetch compliant function, that wraps undici's fetch.
+ *
+ * Behaves the same as any fetch function except:
+ * - Sets a request header called `x-request-trace-id` with a random UUID;
+ * - Sends the request, response, error and/or failure to the Trace system;
+ * - Emits a `http:request` event on every call (success, error, failure).
+ *
+ * Node and Undici realms can't be mixed: passing a Node `Request` with an Undici `FormData` body (or vice versa) throws a `TypeError`.
+ *
+ * @see {@link https://fetch.spec.whatwg.org/}
+ * @param input - URL string, URL object or Request object (undici's or Node's)
+ * @param init - Request options
+ * @returns The HTTP response
+ */
+export declare const outputFetch: OutputFetch;

package/src/http/fetch/index.js

@@ -0,0 +1,78 @@
+import { randomUUID } from 'node:crypto';
+import { logRequest, logResponse, logError, logFailure } from './logger.js';
+import { emitSuccess, emitError, emitFailure } from './events.js';
+import { addRequestIdToResponse } from '../request_tag.js';
+import * as undici from 'undici';
+
+/* Ignore HTTP/2. Check: https://github.com/growthxai/output/issues/299 */
+const customDispatcher = new undici.EnvHttpProxyAgent( { allowH2: false } );
+
+const createUndiciRequest = ( input, init ) => {
+  const isNodeRequest = input instanceof globalThis.Request;
+  const hasNodeFormData = init?.body instanceof globalThis.FormData;
+  const isUndiciRequest = input instanceof undici.Request;
+  const hasUndiciFormData = init?.body instanceof undici.FormData;
+
+  if ( ( isNodeRequest && hasUndiciFormData ) || ( isUndiciRequest && hasNodeFormData ) ) {
+    throw new TypeError( 'Cannot mix Node and Undici Request/FormData realms.' );
+  }
+
+  if ( !isNodeRequest && !hasNodeFormData ) {
+    return new undici.Request( input, init );
+  }
+
+  const request = new globalThis.Request( input, init );
+  return new undici.Request( request.url, request );
+};
+
+/**
+ * A fetch compliant function, that wraps undici's fetch.
+ *
+ * @param {RequestInfo} input - URL string, URL object or Request object (undici's or Node's)
+ * @param {RequestInit} [init] - Request options
+ * @returns {Promise<Response>} The HTTP response
+ */
+export const outputFetch = async ( input, init ) => {
+  const { dispatcher: inputDispatcher, ...requestInit } = init ?? {};
+
+  // Creates a Request object with the many shapes RequestInfo can have
+  const base = createUndiciRequest( input, requestInit );
+
+  // Creates a headers object with the many shapes Request.Headers can have (object, array, Headers)
+  const headers = new undici.Headers( base.headers );
+
+  const requestId = randomUUID();
+  headers.set( 'x-request-trace-id', requestId );
+  const request = new undici.Request( base, { headers } );
+
+  const method = request.method;
+  const url = request.url;
+  const startedAt = Date.now();
+
+  await logRequest( { requestId, request } );
+
+  // this allows for users not only to override the dispatcher but also to define it as undefined and remove it altogether.
+  const dispatcher = Object.hasOwn( init ?? {}, 'dispatcher' ) ? inputDispatcher : customDispatcher;
+  try {
+    const response = await undici.fetch( request, dispatcher ? { dispatcher } : undefined );
+    const durationMs = Date.now() - startedAt;
+    const { status } = response;
+
+    // This enriches the response of the request id, so it is identifiable later.
+    addRequestIdToResponse( response, requestId );
+
+    if ( status > 399 ) {
+      await logError( { requestId, response } );
+      emitError( { requestId, method, url, status, durationMs } );
+      return response;
+    }
+    await logResponse( { requestId, response } );
+    emitSuccess( { requestId, method, url, status, durationMs } );
+    return response;
+  } catch ( error ) {
+    const durationMs = Date.now() - startedAt;
+    logFailure( { requestId, error } );
+    emitFailure( { requestId, method, url, durationMs } );
+    throw error;
+  }
+};

package/src/http/fetch/logger.d.ts

@@ -0,0 +1,10 @@
+import { Attribute } from '#trace_attribute';
+
+/** Trace attribute (`http:request:count`) added to every HTTP request made with `outputFetch` or `createKyClient` */
+export declare class HTTPRequestCount extends Attribute.BaseAttribute {
+  static TYPE: 'http:request:count';
+  type: typeof HTTPRequestCount.TYPE;
+  url: string;
+  requestId: string;
+  constructor( url: string, requestId: string );
+}

package/src/http/fetch/logger.js

@@ -0,0 +1,56 @@
+import { addEventActionWithContext, EventAction } from '#tracing';
+import { BaseAttribute } from '#trace_attribute';
+import { config } from '../config.js';
+import { redactHeaders } from '#helpers/redact';
+import { consumeBody } from '#helpers/fetch';
+
+export class HTTPRequestCount extends BaseAttribute {
+  static TYPE = 'http:request:count';
+  url;
+  requestId;
+
+  constructor( url, requestId ) {
+    super( HTTPRequestCount.TYPE );
+    this.url = url;
+    this.requestId = requestId;
+  }
+}
+
+/**
+ * Sends the trace start event for an http request
+ *
+ * @param options
+ * @param options.requestId - id of the request
+ * @param options.request - The HTTP Request object
+ */
+export const logRequest = async ( { requestId, request } ) => {
+  addEventActionWithContext( EventAction.START, {
+    id: requestId, kind: 'http', name: 'request', details: {
+      method: request.method,
+      url: request.url,
+      ...( config.logVerbose && { headers: redactHeaders( request.headers ), body: await consumeBody( request.clone() ) } )
+    }
+  } );
+  addEventActionWithContext( EventAction.ADD_ATTR, { id: requestId, details: new HTTPRequestCount( request.url, requestId ) } );
+};
+
+export const logError = async ( { requestId, response } ) =>
+  addEventActionWithContext( EventAction.ERROR, {
+    id: requestId, details: {
+      status: response.status,
+      statusText: response.statusText,
+      ...( config.logVerbose && { headers: redactHeaders( response.headers ), body: await consumeBody( response.clone() ) } )
+    }
+  } );
+
+export const logResponse = async ( { requestId, response } ) =>
+  addEventActionWithContext( EventAction.END, {
+    id: requestId, details: {
+      status: response.status,
+      statusText: response.statusText,
+      ...( config.logVerbose && { headers: redactHeaders( response.headers ), body: await consumeBody( response.clone() ) } )
+    }
+  } );
+
+export const logFailure = ( { requestId, error } ) =>
+  addEventActionWithContext( EventAction.ERROR, { id: requestId, details: error } );

package/src/http/index.d.ts

@@ -0,0 +1,27 @@
+/** Payload of the `http:request` event */
+export type HttpRequestEvent = {
+  requestId: string;
+  method: string;
+  url: string;
+  status: number | undefined;
+  durationMs: number;
+  outcome: 'success' | 'error' | 'failure';
+};
+
+/** Payload of the `cost:http:request` event */
+export type HttpRequestCostEvent = {
+  type: 'http:request:cost';
+  requestId: string;
+  url: string;
+  total: number;
+};
+
+export { outputFetch } from './fetch/index.js';
+export { HTTPRequestCount } from './fetch/logger.js';
+export { createKyClient } from './ky/index.js';
+
+export { addRequestCost, HTTPRequestCost } from './cost.js';
+
+/** Re-export ky library for convenience. */
+export * as ky from 'ky';
+export * as undici from 'undici';

package/src/http/index.js

@@ -0,0 +1,9 @@
+export { outputFetch } from './fetch/index.js';
+export { HTTPRequestCount } from './fetch/logger.js';
+export { createKyClient } from './ky/index.js';
+
+export { addRequestCost, HTTPRequestCost } from './cost.js';
+
+/** Re-export ky library for convenience. */
+export * as ky from 'ky';
+export * as undici from 'undici';

package/src/http/ky/index.d.ts

@@ -0,0 +1,25 @@
+import type { KyInstance, Options } from 'ky';
+
+/**
+ * Creates a ky client.
+ *
+ * This client uses a custom fetch that introduces hooks to integrate with Output.ai tracing.
+ *
+ * @example
+ * ```ts
+ * import { createKyClient } from '@outputai/core/http';
+ *
+ * const client = createKyClient({
+ *   prefix: 'https://api.example.com',
+ *   timeout: 30000,
+ *   retry: { limit: 3 }
+ * });
+ *
+ * const response = await client.get('users/1');
+ * const data = await response.json();
+ * ```
+ *
+ * @param options - The ky options to extend the base client.
+ * @returns A ky instance extended with Output.ai tracing hooks.
+ */
+export declare function createKyClient( options?: Options ): KyInstance;

package/src/http/ky/index.js

@@ -0,0 +1,10 @@
+import ky from 'ky';
+import { outputFetch } from '../fetch/index.js';
+
+/**
+ * Creates a ky client that uses `outputFetch`.
+ *
+ * @param {import('ky').Options} options - The ky options to extend the base client.
+ * @returns {import('ky').KyInstance} A ky instance extended with Output.ai tracing hooks.
+ */
+export const createKyClient = ( options = {} ) => ky.create( { fetch: outputFetch, ...options } );

package/src/http/request_tag.js

@@ -0,0 +1,30 @@
+/**
+ * Symbol used to store request id in the response object.
+ */
+export const requestIdSymbol = Symbol( 'request_id' );
+
+/**
+ * Tag a response in place with its request id so downstream code (e.g.
+ * `addRequestCost`) can correlate. Stores the id under a private symbol AND
+ * patches `clone()` so the tag propagates to clones — ky clones the response
+ * before invoking `afterResponse` hooks, and undici headers are immutable on
+ * received responses, so a symbol re-attached inside `clone()` is the only
+ * path that survives.
+ *
+ * @param {Response} response
+ * @param {string} requestId
+ */
+export const addRequestIdToResponse = ( response, requestId ) => {
+  Object.defineProperty( response, requestIdSymbol, { value: requestId, enumerable: false, configurable: false, writable: false } );
+  const originalClone = response.clone.bind( response );
+  Object.defineProperty( response, 'clone', {
+    value: function clone() {
+      const cloned = originalClone();
+      addRequestIdToResponse( cloned, requestId );
+      return cloned;
+    },
+    enumerable: false,
+    configurable: true,
+    writable: true
+  } );
+};

package/src/tracing/trace_attribute.d.ts

@@ -4,22 +4,5 @@ export declare namespace Attribute {
     constructor( type: string );
   }
 
-  export class HTTPRequestCount extends BaseAttribute {
-    static TYPE: 'http:request:count';
-    type: typeof HTTPRequestCount.TYPE;
-    url: string;
-    requestId: string;
-    constructor( url: string, requestId: string );
-  }
-
-  export class HTTPRequestCost extends BaseAttribute {
-    static TYPE: 'http:request:cost';
-    type: typeof HTTPRequestCost.TYPE;
-    url: string;
-    requestId: string;
-    total: number;
-    constructor( url: string, requestId: string, total: number );
-  }
-
   export type Instance = BaseAttribute;
 }

package/src/tracing/trace_attribute.js

@@ -9,37 +9,9 @@ export class BaseAttribute {
   }
 }
 
-class HTTPRequestCount extends BaseAttribute {
-  static TYPE = 'http:request:count';
-  url;
-  requestId;
-
-  constructor( url, requestId ) {
-    super( HTTPRequestCount.TYPE );
-    this.url = url;
-    this.requestId = requestId;
-  }
-}
-
-class HTTPRequestCost extends BaseAttribute {
-  static TYPE = 'http:request:cost';
-  url;
-  requestId;
-  total = 0;
-
-  constructor( url, requestId, total ) {
-    super( HTTPRequestCost.TYPE );
-    this.url = url;
-    this.requestId = requestId;
-    this.total = total;
-  }
-}
-
 /**
  * Types of ADD_ATTR attributes
  */
 export const Attribute = {
-  BaseAttribute,
-  HTTPRequestCost,
-  HTTPRequestCount
+  BaseAttribute
 };

package/src/worker/configs.js

@@ -22,13 +22,31 @@ const envVarSchema = z.object( {
   // 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.
   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.
-  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.
-  TEMPORAL_MAX_CACHED_WORKFLOWS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 1000 ) ),
+  /*
+  Workflow tasks that may run at once. These are short state transitions, so this is rarely the
+  throughput limit - activity concurrency above is. Left unset so @temporalio/worker applies its
+  own default of 40; the startup 'Worker sizing' log reports it as workflowTaskSlots.
+  https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#maxconcurrentworkflowtaskexecutions
+  */
+  TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_EXECUTIONS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().optional() ),
+  /*
+  LRU cache for sticky workflow execution, holding each workflow's state until it completes or is
+  evicted. Left unset so @temporalio/worker sizes it from the isolate's heap limit, which a flat
+  value here cannot track. That formula assumes roughly 600 cached workflows per GB, so set this
+  where payloads are heavier - the startup 'Worker sizing' log reports what it resolved to.
+  https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#maxcachedworkflows
+  */
+  TEMPORAL_MAX_CACHED_WORKFLOWS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().optional() ),
   // How aggressively the worker pulls tasks from Temporal.
   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 ) ),
+  /*
+  Threads running workflow sandboxes. Each is a V8 isolate and NODE_OPTIONS heap caps apply per
+  isolate, so this multiplies the heap the process can commit - the startup 'Worker sizing'
+  log reports the total. Left unset so @temporalio/worker picks: 1 with reuseV8Context, 2 without.
+  https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#workflowthreadpoolsize
+  */
+  TEMPORAL_WORKFLOW_THREAD_POOL_SIZE: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().optional() ),
   // JSON-encoded Temporal Worker tuner options.
   TEMPORAL_WORKER_TUNER: workerTunerEnvSchema,
   // Activity configs
@@ -64,6 +82,7 @@ export const maxConcurrentWorkflowTaskExecutions = envVars.TEMPORAL_MAX_CONCURRE
 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 workflowThreadPoolSize = envVars.TEMPORAL_WORKFLOW_THREAD_POOL_SIZE;
 export const workerTuner = envVars.TEMPORAL_WORKER_TUNER;
 export const namespace = envVars.TEMPORAL_NAMESPACE;
 export const taskQueue = envVars.OUTPUT_CATALOG_ID;

package/src/worker/index.js

@@ -1,5 +1,5 @@
 import { Worker, NativeConnection } from '@temporalio/worker';
-import * as configs from './configs.js';
+import { address, apiKey, namespace, taskQueue, grpcProxy, hookFlushTimeoutMs } from './configs.js';
 import { loadActivities } from './loader/activities.js';
 import { loadWorkflows } from './loader/workflows.js';
 import { loadHooks } from './loader/hooks.js';
@@ -15,7 +15,7 @@ import { CatalogPublisher } from './catalog_workflow/catalog_publisher.js';
 import { mainEventBus } from '#bus';
 import { flushPendingHooks } from '#hooks/pending_hooks';
 import { BusEventType } from '#consts';
-import { setupTelemetry } from './telemetry.js';
+import { setupTelemetry, logIsolateSizing } from './telemetry.js';
 import { TemporalConnectionMonitor } from './connection_monitor.js';
 import { bindGlobalFunctions } from './global_functions.js';
 import { setupClientConfig } from '#temporal/client';
@@ -24,28 +24,12 @@ import { setupTemporalLogger } from './temporal_logger.js';
 import { WorkerRunner } from './worker_runner.js';
 import { shutdownServices } from './shutdown.js';
 import { init as initCredentials } from '#credentials/init';
+import { buildWorkerOptions } from './worker_options.js';
 
 import './log_hooks.js';
 
 const log = createChildLogger( 'Worker' );
 
-const {
-  address,
-  apiKey,
-  namespace,
-  taskQueue,
-  grpcProxy,
-  maxConcurrentWorkflowTaskExecutions,
-  maxConcurrentActivityTaskExecutions,
-  maxCachedWorkflows,
-  maxConcurrentActivityTaskPolls,
-  maxConcurrentWorkflowTaskPolls,
-  shutdownForceTime,
-  shutdownGraceTime,
-  hookFlushTimeoutMs,
-  workerTuner
-} = configs;
-
 const services = {
   connection: null,
   connectionMonitor: null,
@@ -113,34 +97,19 @@ const execute = async () => {
   await run( () => services.catalogPublisher.run() );
 
   log.info( 'Creating Temporal worker...' );
-  const worker = await run( () => {
-    if ( workerTuner ) {
-      log.info( 'Using worker tuner options', { ...workerTuner } );
-    }
-
-    return Worker.create( {
-      connection,
-      namespace,
-      taskQueue,
-      workflowsPath,
-      activities,
-      sinks,
-      interceptors: initInterceptors( { activities, workflows } ),
-      // tuner isn't compatible with concurrent task executions configs
-      ...( workerTuner ? {
-        tuner: workerTuner
-      } : {
-        maxConcurrentWorkflowTaskExecutions,
-        maxConcurrentActivityTaskExecutions
-      } ),
-      maxCachedWorkflows,
-      maxConcurrentActivityTaskPolls,
-      maxConcurrentWorkflowTaskPolls,
-      bundlerOptions: { webpackConfigHook },
-      ...( shutdownForceTime !== undefined && { shutdownForceTime } ),
-      ...( shutdownGraceTime !== undefined && { shutdownGraceTime } )
-    } );
-  } );
+  const worker = await run( () => Worker.create( {
+    connection,
+    namespace,
+    taskQueue,
+    workflowsPath,
+    activities,
+    sinks,
+    interceptors: initInterceptors( { activities, workflows } ),
+    bundlerOptions: { webpackConfigHook },
+    ...buildWorkerOptions()
+  } ) );
+
+  run( () => logIsolateSizing( { worker } ) );
 
   log.info( 'Setting up telemetry...' );
   run( () => setupTelemetry( { worker } ) );

package/src/worker/interceptors/activity.js

@@ -103,7 +103,6 @@ export class ActivityExecutionInterceptor {
       const nonRetryable = error instanceof FatalError || inheritsFromAnyNamedType( error, activityInfo.retryPolicy?.nonRetryableErrorTypes ?? [] );
       throw ApplicationFailure.fromError( unwrappedError, {
         nonRetryable,
-        cause: unwrappedError,
         details: [ { error: serializeError( unwrappedError, { dropKeys: [ 'stack' ] } ) } ]
       } );
     } finally {

package/src/worker/interceptors/workflow.js

@@ -89,7 +89,6 @@ class WorkflowExecutionInterceptor {
         const unwrappedError = error instanceof TransparentFatalError ? error.cause : error;
         sinks.workflow.error( serializeError( unwrappedError ) );
         throw ApplicationFailure.fromError( unwrappedError, {
-          cause: unwrappedError,
           nonRetryable: true,
           details: [ { error: serializeError( unwrappedError, { dropKeys: [ 'stack' ] } ) } ]
         } );

package/src/worker/telemetry.js

@@ -1,21 +1,141 @@
+import { totalmem } from 'node:os';
+import { getHeapStatistics } from 'node:v8';
 import { serializeError } from '#helpers/error_serializer';
 import { createChildLogger } from '#logger';
 import { workerTelemetryIntervalMs } from './configs.js';
 
 const log = createChildLogger( 'Telemetry' );
 
+/**
+ * Resolve the memory limit to compare the worker against: the container's limit, or the
+ * machine's total memory when there is none.
+ *
+ * `process.constrainedMemory()` returns a sentinel near 2^64 rather than 0 when the process is
+ * unconstrained, so values at or above the machine's memory are treated as no limit.
+ *
+ * @returns {number} Bytes.
+ */
+const resolveMemoryLimit = () => {
+  const constrainedMemory = process.constrainedMemory();
+  const machineMemory = totalmem();
+  return constrainedMemory > 0 && constrainedMemory < machineMemory ? constrainedMemory : machineMemory;
+};
+
+/**
+ * Log the worker's isolate and cache sizing. Warn when the projected
+ * heap exceeds the memory limit, or when workflow task slots exceed
+ * the cache.
+ *
+ * The worker runs one isolate on the main thread and one per workflow
+ * thread. A NODE_OPTIONS heap cap applies to each isolate, not to the
+ * process, so on a 4 GB container `--max-old-space-size-percentage=85`
+ * allows each isolate ~3.4 GB and two isolates can commit well over
+ * the container's memory.
+ *
+ * The cache and the task slots are sized independently:
+ * `@temporalio/worker` derives `maxCachedWorkflows` from the heap limit
+ * but fixes `workflowTaskSlots` at 40. On a small container the slots
+ * can exceed the cache, which causes tasks to evict each other's
+ * workflows and forces history replays.
+ *
+ * Logged fields are read from `worker.options`, so each is the resolved
+ * value rather than the requested one:
+ *
+ * - `workflowThreadPoolSize`: threads running workflow sandboxes.
+ *   Defaults to 1 with `reuseV8Context`, 2 without. Ignored under
+ *   `debugMode`.
+ * - `reuseV8Context`: whether workflows share one VM context per thread
+ *   or each get a new one. Enabled by default. Upstream estimates
+ *   roughly 600 cached workflows per GB with it and 250 without.
+ * - `isolateCount`: `1 + workflowThreadPoolSize`, the multiplier on the
+ *   per-isolate heap cap. 1 under `debugMode`, which runs workflows in
+ *   the main isolate and spawns no workflow threads.
+ * - `heapSizeLimit`: the main isolate's V8 heap ceiling, as resolved
+ *   from NODE_OPTIONS.
+ * - `projectedCommittedHeap`: `isolateCount * heapSizeLimit`, the heap
+ *   the process can commit if every isolate fills. Only the main
+ *   thread's limit is readable, so this assumes the workflow threads
+ *   have the same one.
+ * - `memoryLimit`: the limit the projection is compared against. The
+ *   container's limit, or the machine's total memory when unconstrained.
+ * - `maxCachedWorkflows`: sticky cache size. Derived from
+ *   `heapSizeLimit` when TEMPORAL_MAX_CACHED_WORKFLOWS is unset.
+ * - `workflowTaskSlots`: workflow tasks that may run at once, from the
+ *   tuner. Undefined with a resource-based tuner, which sizes slots at
+ *   runtime.
+ *
+ * @param {object} params Parameters.
+ * @param {import('@temporalio/worker').Worker} params.worker The created Temporal worker.
+ */
+export const logIsolateSizing = ( { worker } ) => {
+  const { workflowThreadPoolSize, reuseV8Context, maxCachedWorkflows, tuner, debugMode } = worker.options;
+  // debugMode runs workflows in the main isolate and spawns no workflow threads.
+  const isolateCount = debugMode ? 1 : 1 + workflowThreadPoolSize;
+  const heapSizeLimit = getHeapStatistics().heap_size_limit;
+  const memoryLimit = resolveMemoryLimit();
+  const workflowTaskSlots = tuner?.workflowTaskSlotSupplier?.numSlots;
+  const projectedCommittedHeap = isolateCount * heapSizeLimit;
+
+  log.info( 'Worker sizing', {
+    workflowThreadPoolSize,
+    reuseV8Context,
+    isolateCount,
+    heapSizeLimit,
+    projectedCommittedHeap,
+    memoryLimit,
+    maxCachedWorkflows,
+    workflowTaskSlots
+  } );
+
+  if ( projectedCommittedHeap > memoryLimit ) {
+    log.warn( 'Worker isolates may commit more heap than the host allows', { isolateCount, heapSizeLimit, projectedCommittedHeap, memoryLimit } );
+  }
+
+  if ( workflowTaskSlots > maxCachedWorkflows ) {
+    log.warn( 'Worker runs more workflow tasks than it can cache, forcing replays', { workflowTaskSlots, maxCachedWorkflows } );
+  }
+};
+
+/**
+ * Start an interval that logs worker status and memory every
+ * OUTPUT_WORKER_TELEMETRY_INTERVAL_MS. Disabled when it is 0.
+ *
+ * Each record holds the Temporal worker's `status` and a `memory`
+ * block. The memory fields mix process-wide and main-isolate scopes:
+ *
+ * - `availableMemory`: memory the process can still allocate, within
+ *   the container limit.
+ * - `memoryLimit`: the container's limit, or the machine's total memory
+ *   when unconstrained.
+ * - `memoryUsage`: raw `process.memoryUsage()`. `rss` is process-wide;
+ *   `heapTotal` and `heapUsed` cover only the main isolate.
+ * - `nonMainHeap`: `memoryUsage.rss - memoryUsage.heapUsed`, the
+ *   resident memory outside the main isolate's live objects: workflow
+ *   thread heaps, Rust core allocations, buffers, and heap pages V8 has
+ *   committed but not filled. An upper bound on the workflow thread
+ *   heap, not a measurement of it. Cached workflow memory is counted
+ *   here, so it grows with the cache while `heapUsed` stays flat.
+ * - `heapSizeLimit`: the main isolate's V8 heap ceiling. Constant, but
+ *   included in each sample so records are self-contained.
+ *
+ * @param {object} params Parameters.
+ * @param {import('@temporalio/worker').Worker} params.worker The created Temporal worker.
+ */
 export const setupTelemetry = ( { worker } ) => {
   if ( workerTelemetryIntervalMs <= 0 ) {
     return;
   }
   setInterval( () => {
     try {
+      const memoryUsage = process.memoryUsage();
       log.info( 'Worker', {
         status: worker.getStatus(),
         memory: {
           availableMemory: process.availableMemory(),
-          constrainedMemory: process.constrainedMemory(),
-          memoryUsage: process.memoryUsage()
+          memoryLimit: resolveMemoryLimit(),
+          memoryUsage,
+          nonMainHeap: memoryUsage.rss - memoryUsage.heapUsed,
+          heapSizeLimit: getHeapStatistics().heap_size_limit
         }
       } );
     } catch ( error ) {

package/src/worker/worker_options.js

@@ -0,0 +1,43 @@
+import * as configs from './configs.js';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Worker' );
+
+const {
+  maxConcurrentWorkflowTaskExecutions,
+  maxConcurrentActivityTaskExecutions,
+  maxCachedWorkflows,
+  maxConcurrentActivityTaskPolls,
+  maxConcurrentWorkflowTaskPolls,
+  workflowThreadPoolSize,
+  shutdownForceTime,
+  shutdownGraceTime,
+  workerTuner
+} = configs;
+
+/**
+ * Builds the concurrency, cache and shutdown options passed to `Worker.create`.
+ * Unset values are omitted so @temporalio/worker applies its own defaults.
+ * @returns {object} partial Temporal worker options
+ */
+export const buildWorkerOptions = () => {
+  if ( workerTuner ) {
+    log.info( 'Using worker tuner options', { ...workerTuner } );
+  }
+  return {
+    // tuner isn't compatible with concurrent task executions configs
+    ...( workerTuner ? {
+      tuner: workerTuner
+    } : {
+      ...( maxConcurrentWorkflowTaskExecutions !== undefined && { maxConcurrentWorkflowTaskExecutions } ),
+      maxConcurrentActivityTaskExecutions
+    } ),
+    ...( maxCachedWorkflows !== undefined && { maxCachedWorkflows } ),
+    maxConcurrentActivityTaskPolls,
+    maxConcurrentWorkflowTaskPolls,
+    // Omitted when unset so @temporalio/worker applies its own default, which depends on reuseV8Context.
+    ...( workflowThreadPoolSize !== undefined && { workflowThreadPoolSize } ),
+    ...( shutdownForceTime !== undefined && { shutdownForceTime } ),
+    ...( shutdownGraceTime !== undefined && { shutdownGraceTime } )
+  };
+};