@outputai/core 0.15.1-next.4a437bf.0 → 0.15.1-next.8ef04e2.0

package/src/llm/utils/wrap.js

@@ -0,0 +1,277 @@
+import { extractSources } from './sources.js';
+import { serializeImagesFromResponse } from './image.js';
+import { addEventActionWithContext, EventAction } from '#tracing';
+import { mapAiError } from './error_handler.js';
+import { isPromise } from 'node:util/types';
+import { FatalError } from '#errors';
+import { Logger } from '#runtime_logger';
+import { Metering } from './metering.js';
+import { randomBytes } from 'node:crypto';
+
+/** Creates a proxy of the AI SDK response and attach virtual getters to it based on an object map */
+const createResponseProxy = ( { response, properties } ) => new Proxy( response, {
+  get( target, prop, receiver ) {
+    return Object.hasOwn( properties, prop ) ? properties[prop] : Reflect.get( target, prop, receiver );
+  }
+} );
+
+/** Generate a trace id, starts the tracing and return the id */
+const startTrace = ( { name, prompt } ) => {
+  const traceId = `${name}-${Date.now()}-${randomBytes( 4 ).toString( 'hex' )}`;
+  addEventActionWithContext( EventAction.START, { kind: 'llm', id: traceId, name, details: { prompt } } );
+  return traceId;
+};
+
+/** Handle AI SDK errors: map them, add an error trace entry and return the new error */
+const handleAiSdkError = ( { traceId, error: originalError } ) => {
+  const error = mapAiError( originalError );
+  addEventActionWithContext( EventAction.ERROR, { id: traceId, details: error } );
+  return error;
+};
+
+/**
+ * Handle a failure of our own response handling: wrap it, add an error trace entry and return it.
+ * Fatal on purpose - such a failure is deterministic, so a retry pays for the model call again and
+ * fails the same way.
+ */
+const handleResponseError = ( { traceId, error: cause } ) => {
+  const error = new FatalError( 'AI SDK response handling failed.', { cause } );
+  addEventActionWithContext( EventAction.ERROR, { id: traceId, details: error } );
+  return error;
+};
+
+/** Invokes an async function, wrapped in a try/catch, return { result, error } */
+const inlineTryAsync = async fn => {
+  try {
+    return { result: await fn(), error: null };
+  } catch ( error ) {
+    return { result: null, error };
+  }
+};
+
+/**
+ * Runs a completing AI SDK text call (`generateText`, `generateTextWithStreaming`,
+ * `Agent.generate`, `Agent.generateWithStreaming`): starts the LLM trace, runs `fn`, ends the trace
+ * and returns the response proxied with `result` (`text`), `cost` and merged `sources`.
+ *
+ * `fn` receives `onStepEndHook` to wire into the SDK `onStepEnd`, so the usage of every completed
+ * step is collected as the call progresses and still lands when `fn` throws after the model ran.
+ * The response `fn` returns is billed directly, and its aggregate usage takes precedence over the
+ * collected steps. Trace output keeps raw `response.usage`; normalized usage and cost are trace
+ * attributes.
+ *
+ * Reading the billed response is guarded: a throw from `fn` is mapped as an SDK error, while a
+ * failure of our own handling becomes a `FatalError` recorded on the trace. The proxy is built
+ * before the trace ends, so a call that fails there never leaves an `end` entry next to an `error`.
+ *
+ * @param {object} args
+ * @param {string} args.name - Trace event name
+ * @param {object} args.prompt - Loaded prompt (`config.provider` / `config.model` used for cost)
+ * @param {( wiring: { onStepEndHook: Function } ) => Promise<object>} args.fn - AI SDK call; wire
+ *   `onStepEndHook` into the call `onStepEnd` and return the SDK response
+ * @returns {Promise<object>} Proxied SDK response
+ */
+export const wrapTextGeneration = async ( { name, prompt, fn } ) => {
+  const traceId = startTrace( { name, prompt } );
+
+  const metering = new Metering( { traceId, prompt } );
+
+  const onStepEndHook = metering.recordStep;
+
+  const { result: response, error } = await inlineTryAsync( () => fn( { onStepEndHook } ) );
+
+  await metering.bill( response );
+
+  if ( error ) {
+    throw handleAiSdkError( { traceId, error } );
+  }
+
+  try {
+    const { text: result, finalStep, usage } = response;
+    const providerMetadata = finalStep?.providerMetadata;
+    const sources = extractSources( response );
+
+    // Create proxy first, as this could theoretically fail
+    const responseProxy = createResponseProxy( { response, properties: { cost: metering.attributes.cost, sources, result } } );
+    addEventActionWithContext( EventAction.END, { id: traceId, details: { result, usage, providerMetadata, sources } } );
+
+    return responseProxy;
+  } catch ( error ) {
+    throw handleResponseError( { traceId, error } );
+  }
+};
+
+/**
+ * Runs `generateImage`: starts the LLM trace, meters the returned usage, ends the trace and returns
+ * the response proxied with `result` (the first `image`) and `cost`.
+ *
+ * Image calls expose no step lifecycle, so usage is read from the response. With no
+ * step loop and no output parsing, a throw from `fn` happens before any usage exists, so it is
+ * mapped and recorded without metering. Reading the billed response is guarded the same way
+ * `wrapTextGeneration` guards it: a failure there is a `FatalError` recorded after billing.
+ *
+ * @param {object} args
+ * @param {string} args.name - Trace event name
+ * @param {object} args.prompt - Loaded prompt (`config.provider` / `config.model` used for cost)
+ * @param {() => Promise<object>} args.fn - AI SDK call; must return the SDK response
+ * @returns {Promise<object>} Proxied SDK response
+ */
+export const wrapImageGeneration = async ( { name, prompt, fn } ) => {
+  const traceId = startTrace( { name, prompt } );
+
+  const metering = new Metering( { traceId, prompt } );
+
+  const { result: response, error } = await inlineTryAsync( fn );
+
+  if ( error ) {
+    throw handleAiSdkError( { traceId, error } );
+  }
+
+  await metering.bill( response );
+
+  try {
+    const { usage, image: result, providerMetadata } = response;
+    const serializeImages = serializeImagesFromResponse( response );
+
+    // Create proxy first, as this could theoretically fail
+    const responseProxy = createResponseProxy( { response, properties: { cost: metering.attributes.cost, result } } );
+
+    addEventActionWithContext( EventAction.END, { id: traceId, details: { result: serializeImages, usage, providerMetadata } } );
+    return responseProxy;
+  } catch ( error ) {
+    throw handleResponseError( { traceId, error } );
+  }
+};
+
+/** Awaits a consumer callback, logging and swallowing its failures: the hooks are fire and forget */
+const invokeCallback = async ( cb, args, cbName ) => {
+  if ( typeof cb === 'function' ) {
+    try {
+      await cb( ...args );
+    } catch ( e ) {
+      Logger.error( `Stream ${cbName}() callback failed`, { namespace: 'LLM', error: e?.message || String( e ) } );
+    }
+  }
+};
+
+/**
+ * Starts an LLM trace around a live AI SDK stream (`streamText`, `Agent.stream`).
+ *
+ * `fn` receives `onEndHook(response, callback)` and `onErrorHook(event, callback)` to wire into the
+ * SDK `onEnd` / `onError`, plus `onStepEndHook` and `onAbortHook` for `onStepEnd` / `onAbort`. Both
+ * terminal hooks bill, end or record the trace, then invoke `callback`; a `callback` that is not a
+ * function is skipped, and callback failures are logged, never rethrown.
+ *
+ * Neither hook throws, because the SDK invokes them through `notify`, which swallows callback
+ * failures and discards their return: a failure while reading the response would vanish, so it is
+ * logged and recorded as a trace error here instead. An `onError`
+ * event carrying no `Error` is normalized to `Streaming failed.` with the original value as `cause`,
+ * so the trace always closes and the consumer callback always runs.
+ *
+ * Metering is fed by `onStepEndHook`, which collects step usage so the tokens survive the exits
+ * that report no response: `NoOutputGeneratedError` skips `onEnd`, and an abort fires neither
+ * terminal hook. `onAbortHook` bills that case, and the SDK awaits it before enqueueing the abort
+ * part, so billing from there always lands before the consumer observes the cancellation.
+ *
+ * A throw or rejected Promise from `fn` (stream creation / Agent setup) is mapped and recorded on
+ * the trace; a non-Promise return (the `streamText` stream) is returned as is, with a rejection of
+ * its `output` promise recorded without being swallowed from the consumer. An abort on
+ * `abortSignal` records its reason as a trace error, and the listener is removed when the stream
+ * ends, reports an error, or fails during setup. An abort the SDK raises on its own timeout leaves
+ * `abortSignal` untouched, so `onAbort` records that one instead.
+ *
+ * @param {object} args
+ * @param {string} args.name - Trace event name
+ * @param {object} args.prompt - Loaded prompt (`config.provider` / `config.model` used for cost)
+ * @param {AbortSignal} [args.abortSignal] - Optional signal used to trace stream cancellation
+ * @param {( wiring: { onEndHook: Function, onErrorHook: Function, onStepEndHook: Function,
+ *   onAbortHook: Function } ) => object | Promise<object>} args.fn - Wire the hooks into the call
+ *   and return the SDK stream, or a Promise of that stream (`Agent.stream`)
+ * @returns {object | Promise<object>} Value returned by `fn`; a rejected Promise is remapped
+ */
+export const wrapStream = ( { name, prompt, abortSignal, fn } ) => {
+  const traceId = startTrace( { name, prompt } );
+  const metering = new Metering( { traceId, prompt } );
+
+  const handleAbort = () => {
+    const error = abortSignal?.reason instanceof Error ? abortSignal.reason : new Error( 'Streaming aborted.', { cause: abortSignal?.reason } );
+    handleAiSdkError( { traceId, error } );
+  };
+
+  if ( abortSignal ) {
+    if ( abortSignal.aborted ) {
+      handleAbort();
+    } else {
+      abortSignal.addEventListener( 'abort', handleAbort, { once: true } );
+    }
+  }
+  const removeAbortListener = () => abortSignal?.removeEventListener( 'abort', handleAbort );
+
+  const onStepEndHook = metering.recordStep;
+
+  const onAbortHook = async () => {
+    removeAbortListener();
+
+    await metering.bill();
+    // abortion was caused by timeout and not signal
+    if ( !abortSignal?.aborted ) {
+      handleAiSdkError( { traceId, error: new Error( 'Streaming timed out.' ) } );
+    }
+  };
+
+  const onEndHook = async ( response, callback ) => {
+    removeAbortListener();
+
+    await metering.bill( response );
+
+    try {
+      const { text: result, finalStep, usage } = response;
+      const providerMetadata = finalStep?.providerMetadata;
+      const sources = extractSources( response );
+
+      const proxyResponse = createResponseProxy( { response, properties: { cost: metering.attributes.cost, sources, result } } );
+      addEventActionWithContext( EventAction.END, { id: traceId, details: { result, usage, providerMetadata, sources } } );
+
+      await invokeCallback( callback, [ proxyResponse ], 'onEnd' );
+    } catch ( error ) {
+      Logger.error( 'AI SDK response handling failed', { namespace: 'LLM', error: error?.message || String( error ) } );
+      handleResponseError( { traceId, error } );
+    }
+  };
+
+  const onErrorHook = async ( event, callback ) => {
+    removeAbortListener();
+    await metering.bill();
+
+    const error = event?.error instanceof Error ? event.error : new Error( 'Streaming failed.', { cause: event?.error } );
+    const mappedError = handleAiSdkError( { traceId, error } );
+    await invokeCallback( callback, [ mappedError ], 'onError' );
+  };
+
+  const handleStreamError = error => {
+    removeAbortListener();
+    return handleAiSdkError( { traceId, error } );
+  };
+
+  const addStreamOutputErrorHandler = stream => {
+    stream.output?.catch( error => handleAiSdkError( { traceId, error } ) );
+    return stream;
+  };
+
+  const createStream = () => {
+    try {
+      return fn( { onEndHook, onErrorHook, onStepEndHook, onAbortHook } );
+    } catch ( error ) {
+      throw handleStreamError( error );
+    }
+  };
+
+  const stream = createStream();
+
+  /** Streams can be a promise or not, for both cases add the handler to catch .output errors, and if it is a promise add a .catch handler to observe errors there as well */
+  return isPromise( stream ) ?
+    stream.then( addStreamOutputErrorHandler ).catch( e => {
+      throw handleStreamError( e );
+    } ) :
+    addStreamOutputErrorHandler( stream );
+};

package/src/llm/validations.js

@@ -0,0 +1,234 @@
+import { Buffer } from 'node:buffer';
+import { z } from 'zod';
+import { ValidationError } from '#errors';
+import { Role } from './consts.js';
+import { promptSchema } from './prompt/validations.js';
+
+const rejectPromptOwnedCallArg = name => z.unknown().optional().refine(
+  value => value === undefined,
+  `${name} must be set in the prompt file, not as a call argument`
+);
+
+// Listed so .strict() callers get the prompt-file message instead of an unrecognized-key error.
+// @TODO Do not drop this later.
+const promptOwnedCallArgRejection = {
+  maxSteps: rejectPromptOwnedCallArg( 'maxSteps' ),
+  skills: rejectPromptOwnedCallArg( 'skills' )
+};
+
+const functionSchema = z.custom( value => typeof value === 'function', 'Expected function' );
+
+const variablesSchema = z.record( z.string(), z.unknown() );
+
+const toolChoiceSchema = z.union( [
+  z.enum( [ 'auto', 'none', 'required' ] ),
+  z.object( {
+    type: z.literal( 'tool' ),
+    toolName: z.string().min( 1 )
+  } ).strict()
+] );
+
+const stopWhenSchema = z.union( [
+  functionSchema,
+  z.array( functionSchema ).min( 1 )
+] );
+
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray( value );
+
+const opaqueObjectSchema = z.custom( isObject, 'Expected object' );
+
+const outputSchema = opaqueObjectSchema;
+
+const toolsSchema = z.record( z.string().min( 1 ), opaqueObjectSchema );
+
+const messageStoreSchema = z.custom(
+  value => value !== null &&
+    typeof value === 'object' &&
+    typeof value.getMessages === 'function' &&
+    typeof value.addMessages === 'function',
+  'Expected an object with getMessages and addMessages functions'
+);
+
+const modelMessageSchema = z.object( {
+  role: z.enum( [ ...Object.values( Role ), 'tool' ] ),
+  content: z.union( [ z.string(), z.array( z.unknown() ) ] )
+} ).loose();
+
+const promptFileSchema = z.string().min( 1 );
+
+const promptInputSchema = z.unknown().transform( ( value, ctx ) => {
+  const result = ( isObject( value ) ? promptSchema : promptFileSchema ).safeParse( value );
+  if ( !result.success ) {
+    for ( const issue of result.error.issues ) {
+      ctx.addIssue( issue );
+    }
+    return value;
+  }
+  return result.data;
+} );
+
+const promptCallFields = {
+  prompt: promptInputSchema,
+  promptDir: z.string().min( 1 ).optional(),
+  variables: variablesSchema.optional()
+};
+
+const textRuntimeCallFields = {
+  abortSignal: z.instanceof( AbortSignal ).optional(),
+  output: outputSchema.optional(),
+  stopWhen: stopWhenSchema.optional(),
+  toolChoice: toolChoiceSchema.optional(),
+  tools: toolsSchema.optional()
+};
+
+const generateTextCallFields = {
+  ...promptCallFields,
+  ...promptOwnedCallArgRejection,
+  ...textRuntimeCallFields
+};
+
+const toPromptArgs = ( { prompt, maxSteps, skills, ...rest } ) => ( {
+  ...( typeof prompt === 'string' ? { promptFile: prompt } : { promptObject: prompt } ),
+  ...rest
+} );
+
+const rejectPromptObjectFileArgs = ( args, ctx ) => {
+  if ( !isObject( args.prompt ) ) {
+    return;
+  }
+
+  for ( const field of [ 'promptDir', 'variables' ] ) {
+    if ( args[field] !== undefined ) {
+      ctx.addIssue( {
+        code: 'custom',
+        path: [ field ],
+        message: `${field} cannot be used when prompt is an object`
+      } );
+    }
+  }
+};
+
+const generateTextArgsSchema = z.object( generateTextCallFields )
+  .strict()
+  .superRefine( rejectPromptObjectFileArgs )
+  .transform( toPromptArgs );
+
+const generateTextWithStreamingArgsSchema = z.object( {
+  ...generateTextCallFields,
+  onChunk: functionSchema.optional()
+} ).strict().superRefine( rejectPromptObjectFileArgs ).transform( toPromptArgs );
+
+const streamTextArgsSchema = z.object( {
+  ...generateTextCallFields,
+  onChunk: functionSchema.optional(),
+  onError: functionSchema.optional(),
+  onEnd: functionSchema.optional()
+} ).strict().superRefine( rejectPromptObjectFileArgs ).transform( toPromptArgs );
+
+const agentCallFields = {
+  ...promptCallFields,
+  ...promptOwnedCallArgRejection,
+  messageStore: messageStoreSchema.optional(),
+  output: outputSchema.optional(),
+  stopWhen: stopWhenSchema.optional(),
+  tools: toolsSchema.optional()
+};
+
+const agentMethodCallFields = {
+  abortSignal: z.instanceof( AbortSignal ).optional(),
+  messages: z.array( modelMessageSchema ).default( [] ),
+  toolChoice: toolChoiceSchema.optional(),
+  ...promptOwnedCallArgRejection
+};
+
+const agentArgsSchema = z.object( agentCallFields )
+  .strict()
+  .superRefine( rejectPromptObjectFileArgs )
+  .transform( toPromptArgs );
+
+const agentGenerateArgsSchema = z.object( agentMethodCallFields ).strict();
+
+const agentGenerateWithStreamingArgsSchema = z.object( {
+  ...agentMethodCallFields,
+  onChunk: functionSchema.optional()
+} ).strict();
+
+const agentStreamArgsSchema = z.object( {
+  ...agentMethodCallFields,
+  onChunk: functionSchema.optional(),
+  onError: functionSchema.optional(),
+  onEnd: functionSchema.optional()
+} ).strict();
+
+const base64StringSchema = z.string()
+  .min( 1 )
+  .regex(
+    /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/,
+    'Image strings must be raw base64 data.'
+  );
+
+const imageDataSchema = z.union( [
+  z.instanceof( Buffer ),
+  z.instanceof( Uint8Array ),
+  z.instanceof( ArrayBuffer ),
+  base64StringSchema
+] );
+
+const imageInputSchema = z.union( [
+  imageDataSchema,
+  z.object( {
+    data: imageDataSchema,
+    mediaType: z.string().min( 1 ).optional()
+  } ).strict()
+] );
+
+const generateImageCallFields = {
+  abortSignal: z.instanceof( AbortSignal ).optional(),
+  images: z.array( imageInputSchema ).min( 1 ).optional(),
+  mask: imageInputSchema.optional(),
+  ...promptCallFields
+};
+
+const generateImageArgsSchema = z.object( generateImageCallFields ).strict().superRefine( ( args, ctx ) => {
+  rejectPromptObjectFileArgs( args, ctx );
+
+  if ( args.mask && !args.images ) {
+    ctx.addIssue( {
+      code: 'custom',
+      path: [ 'mask' ],
+      message: 'mask requires images.'
+    } );
+  }
+} ).transform( toPromptArgs );
+
+const parseSchema = ( schema, input, errorPrefix ) => {
+  const result = schema.safeParse( input );
+  if ( !result.success ) {
+    throw new ValidationError( `${errorPrefix}: ${z.prettifyError( result.error )}` );
+  }
+  return result.data;
+};
+
+export const parseGenerateTextArgs = args =>
+  parseSchema( generateTextArgsSchema, args, 'Invalid generateText() arguments' );
+
+export const parseGenerateTextWithStreamingArgs = args =>
+  parseSchema( generateTextWithStreamingArgsSchema, args, 'Invalid generateTextWithStreaming() arguments' );
+
+export const parseStreamTextArgs = args =>
+  parseSchema( streamTextArgsSchema, args, 'Invalid streamText() arguments' );
+
+export const parseGenerateImageArgs = args =>
+  parseSchema( generateImageArgsSchema, args, 'Invalid generateImage() arguments' );
+
+export const parseAgentArgs = args =>
+  parseSchema( agentArgsSchema, args, 'Invalid Agent() arguments' );
+
+export const parseAgentGenerateArgs = args =>
+  parseSchema( agentGenerateArgsSchema, args ?? {}, 'Invalid Agent.generate() arguments' );
+
+export const parseAgentGenerateWithStreamingArgs = args =>
+  parseSchema( agentGenerateWithStreamingArgsSchema, args ?? {}, 'Invalid Agent.generateWithStreaming() arguments' );
+
+export const parseAgentStreamArgs = args =>
+  parseSchema( agentStreamArgsSchema, args ?? {}, 'Invalid Agent.stream() arguments' );

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

@@ -1,5 +1,7 @@
 /**
  * Tools to interact with filesystem paths
+ *
+ * @deprecated Internal helper with no public replacement, kept only for `@outputai/evals`. It will be removed when evals folds into `@outputai/core`.
  */
 export declare const Path: {
   /**

package/src/sdk/helpers/path.js

@@ -17,6 +17,7 @@ const defaultIgnorePaths = [
   'webpack/bootstrap'
 ];
 
+/** @deprecated Internal helper with no public replacement, kept only for `@outputai/evals`. It will be removed when evals folds into `@outputai/core`. */
 export const Path = {
   resolveInvocationDir: ( additionalIgnorePaths = [] ) => {
     const stack = new Error().stack;

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;