duron 0.3.0-beta.8 → 0.3.0

package/dist/step-manager.js

@@ -1,39 +1,118 @@
+import { context, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
 import fastq from 'fastq';
 import { StepOptionsSchema, } from './action.js';
 import { STEP_STATUS_CANCELLED, STEP_STATUS_COMPLETED, STEP_STATUS_FAILED } from './constants.js';
-import { ActionCancelError, isCancelError, isNonRetriableError, NonRetriableError, StepAlreadyExecutedError, StepTimeoutError, serializeError, UnhandledChildStepsError, } from './errors.js';
-const noopTracerSpan = {
-    setAttribute() {
-    },
-    setAttributes() {
-    },
-    addEvent() {
-    },
-    recordException() {
-    },
-    setStatusOk() {
-    },
-    setStatusError() {
-    },
-    end() {
-    },
-    isRecording() {
-        return false;
-    },
-};
-const createNoopTracer = (name) => ({
-    name,
-    startSpan() {
-        return noopTracerSpan;
-    },
-});
+import { ActionCancelError, isCancelError, isNonRetriableError, isTimeoutError, NonRetriableError, StepAlreadyExecutedError, StepTimeoutError, serializeError, UnhandledChildStepsError, } from './errors.js';
+/**
+ * Inject parent span into a context if we have one.
+ */
+function injectParentSpan(ctx, parentSpan) {
+    return parentSpan ? trace.setSpan(ctx, parentSpan) : ctx;
+}
+/**
+ * Create a context-aware tracer wrapper that automatically injects the parent span.
+ * This ensures spans created by external libraries (like AI SDK) are properly linked
+ * to the current job/step trace hierarchy.
+ */
+function createContextAwareTracer(tracer, parentSpan) {
+    return {
+        startSpan(name, options, ctx) {
+            // Always inject our parent span into the context, regardless of what context is passed.
+            // This is necessary because without global registration, context.active() returns
+            // ROOT_CONTEXT, so external libraries (like AI SDK) that pass context.active()
+            // would otherwise create orphan spans.
+            const baseContext = ctx ?? context.active();
+            const effectiveContext = injectParentSpan(baseContext, parentSpan);
+            return tracer.startSpan(name, options, effectiveContext);
+        },
+        // startActiveSpan has multiple overloads, we need to handle them all
+        startActiveSpan(name, optionsOrFn, ctxOrFn, fn) {
+            // Parse the overloaded arguments
+            let options;
+            let ctx;
+            let callback;
+            if (typeof optionsOrFn === 'function') {
+                // startActiveSpan(name, fn)
+                callback = optionsOrFn;
+            }
+            else if (typeof ctxOrFn === 'function') {
+                // startActiveSpan(name, options, fn)
+                options = optionsOrFn;
+                callback = ctxOrFn;
+            }
+            else {
+                // startActiveSpan(name, options, context, fn)
+                options = optionsOrFn;
+                ctx = ctxOrFn;
+                callback = fn;
+            }
+            const baseContext = ctx ?? context.active();
+            const effectiveContext = injectParentSpan(baseContext, parentSpan);
+            return tracer.startActiveSpan(name, options ?? {}, effectiveContext, callback);
+        },
+    };
+}
+/**
+ * Create a TelemetryContext that wraps an OTel span.
+ */
+function createTelemetryContext(span, tracer) {
+    return {
+        getActiveSpan() {
+            return span ?? undefined;
+        },
+        getTracer(_name) {
+            // Return a context-aware tracer that automatically links spans to the current trace
+            return createContextAwareTracer(tracer, span);
+        },
+        startSpan(name, options) {
+            // Create a child span linked to the current span (job or step)
+            const parentContext = span ? trace.setSpan(context.active(), span) : context.active();
+            return tracer.startSpan(name, { attributes: options?.attributes }, parentContext);
+        },
+        recordMetric(name, value, attributes) {
+            if (span) {
+                span.addEvent(`metric:${name}`, {
+                    'metric.value': value,
+                    ...attributes,
+                });
+            }
+        },
+    };
+}
 import pRetry from './utils/p-retry.js';
 import waitForAbort from './utils/wait-for-abort.js';
+/**
+ * StepStore manages step records in the database.
+ * Provides methods to create, update, and delay steps.
+ */
 export class StepStore {
     #adapter;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new StepStore instance.
+     *
+     * @param adapter - The database adapter to use for step operations
+     */
     constructor(adapter) {
         this.#adapter = adapter;
     }
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
+    /**
+     * Get or create a step record in the database.
+     *
+     * @param jobId - The ID of the job this step belongs to
+     * @param name - The name of the step
+     * @param timeoutMs - Timeout in milliseconds for the step
+     * @param retriesLimit - Maximum number of retries for the step
+     * @param parentStepId - The ID of the parent step (null for root steps)
+     * @param parallel - Whether this step runs in parallel (independent from siblings during time travel)
+     * @returns Promise resolving to the created step ID
+     * @throws Error if step creation fails
+     */
     async getOrCreate(jobId, name, timeoutMs, retriesLimit, parentStepId = null, parallel = false) {
         try {
             return await this.#adapter.createOrRecoverJobStep({
@@ -49,6 +128,15 @@ export class StepStore {
             throw new NonRetriableError(`Failed to get or create step "${name}" for job "${jobId}"`, { cause: error });
         }
     }
+    /**
+     * Update the status of a step in the database.
+     *
+     * @param stepId - The ID of the step to update
+     * @param status - The new status (completed, failed, or cancelled)
+     * @param output - Optional output data for completed steps
+     * @param error - Optional error data for failed steps
+     * @returns Promise resolving to `true` if update succeeded, `false` otherwise
+     */
     async updateStatus(stepId, status, output, error) {
         if (status === STEP_STATUS_COMPLETED) {
             return this.#adapter.completeJobStep({ stepId, output });
@@ -61,28 +149,54 @@ export class StepStore {
         }
         return false;
     }
+    /**
+     * Delay a step execution.
+     * Used when a step fails and needs to be retried after a delay.
+     *
+     * @param stepId - The ID of the step to delay
+     * @param delayMs - The delay in milliseconds before retrying
+     * @param error - The error that caused the delay
+     * @returns Promise resolving to `true` if delayed successfully, `false` otherwise
+     */
     async delay(stepId, delayMs, error) {
         return this.#adapter.delayJobStep({ stepId, delayMs, error });
     }
 }
+/**
+ * StepManager manages steps for a single ActionJob.
+ * Each ActionJob has its own StepManager instance.
+ */
 export class StepManager {
     #jobId;
     #actionName;
     #stepStore;
-    #telemetry;
+    #tracer;
     #queue;
     #logger;
+    // each step name should be executed only once per parent (name + parentStepId)
     #historySteps = new Set();
+    // Store step spans for nested step tracking
     #stepSpans = new Map();
-    #jobSpan = null;
+    // Store the job span for creating step spans
+    #jobSpan;
+    // Factory function to create run functions with the correct parent step ID and abort signal
     #runFnFactory = null;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new StepManager instance.
+     *
+     * @param options - Configuration options for the step manager
+     */
     constructor(options) {
         this.#jobId = options.jobId;
         this.#actionName = options.actionName;
         this.#logger = options.logger;
-        this.#telemetry = options.telemetry;
+        this.#tracer = options.tracer;
         this.#stepStore = new StepStore(options.adapter);
         this.#queue = fastq.promise(async (task) => {
+            // Create composite key: name + parentStepId (allows same name under different parents)
             const stepKey = `${task.parentStepId ?? 'root'}:${task.name}`;
             if (this.#historySteps.has(stepKey)) {
                 throw new StepAlreadyExecutedError(task.name, this.#jobId, this.#actionName);
@@ -91,36 +205,59 @@ export class StepManager {
             return this.#executeStep(task.name, task.cb, task.options, task.abortSignal, task.parentStepId, task.parallel);
         }, options.concurrencyLimit);
     }
+    /**
+     * Set the job span for this step manager.
+     * Called from ActionJob after the job span is created.
+     */
     setJobSpan(span) {
         this.#jobSpan = span;
     }
+    /**
+     * Set the run function factory for executing step definitions from inline steps.
+     * Called from ActionContext after it's initialized.
+     *
+     * @param factory - A function that creates run functions with the correct parent step ID and abort signal
+     */
     setRunFnFactory(factory) {
         this.#runFnFactory = factory;
     }
-    createActionContext(job, action, variables, abortSignal, logger, observeContext) {
-        return new ActionContext(this, job, action, variables, abortSignal, logger, observeContext);
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
+    /**
+     * Create an ActionContext for the action handler.
+     * The context provides access to input, variables, logger, and the step function.
+     *
+     * @param job - The job data including ID, input, and optional group key
+     * @param action - The action definition
+     * @param variables - Variables available to the action
+     * @param abortSignal - Abort signal for cancelling the action
+     * @param logger - Pino child logger for this job
+     * @returns ActionHandlerContext instance
+     */
+    createActionContext(job, action, variables, abortSignal, logger) {
+        const telemetryContext = createTelemetryContext(this.#jobSpan, this.#tracer);
+        return new ActionContext(this, job, action, variables, abortSignal, logger, telemetryContext);
     }
-    createStepObserveContext(stepId) {
+    /**
+     * Create a telemetry context for a step.
+     */
+    createStepTelemetryContext(stepId) {
         const stepSpan = this.#stepSpans.get(stepId);
         if (stepSpan) {
-            return this.#telemetry.createObserveContext(this.#jobId, stepId, stepSpan);
+            return createTelemetryContext(stepSpan, this.#tracer);
         }
-        if (this.#jobSpan) {
-            return this.#telemetry.createObserveContext(this.#jobId, stepId, this.#jobSpan);
-        }
-        return {
-            recordMetric: () => {
-            },
-            addSpanAttribute: () => {
-            },
-            addSpanEvent: () => {
-            },
-            getTracer: (name) => {
-                return createNoopTracer(name);
-            },
-        };
+        // Fallback to job span if step span not found
+        return createTelemetryContext(this.#jobSpan, this.#tracer);
     }
+    /**
+     * Queue a step task for execution.
+     *
+     * @param task - The step task to queue
+     * @returns Promise resolving to the step result
+     */
     async push(task) {
+        // Warn about potential starvation when child steps are queued and all slots are occupied
         if (task.parentStepId !== null && this.#queue.running() >= this.#queue.concurrency) {
             this.#logger.warn({
                 jobId: this.#jobId,
@@ -134,9 +271,28 @@ export class StepManager {
         }
         return this.#queue.push(task);
     }
+    /**
+     * Clean up step queues by waiting for them to drain.
+     * Should be called when the job completes or is cancelled.
+     */
     async drain() {
         await this.#queue.drain();
     }
+    /**
+     * Execute a step with retry logic and timeout handling.
+     * Creates a step record, queues the execution, and handles errors appropriately.
+     *
+     * @param name - The name of the step
+     * @param cb - The step handler function
+     * @param options - Step options including concurrency, retry, and expire settings
+     * @param abortSignal - Abort signal for cancelling the step
+     * @param parentStepId - The ID of the parent step (null for root steps)
+     * @returns Promise resolving to the step result
+     * @throws StepTimeoutError if the step times out
+     * @throws StepCancelError if the step is cancelled
+     * @throws UnhandledChildStepsError if child steps are not awaited
+     * @throws Error if the step fails
+     */
     async #executeStep(name, cb, options, abortSignal, parentStepId, parallel) {
         const expire = options.expire;
         const retryOptions = options.retry;
@@ -146,24 +302,30 @@ export class StepManager {
                 if (abortSignal.aborted) {
                     throw new ActionCancelError(this.#actionName, this.#jobId, { cause: 'step cancelled before create step' });
                 }
+                // Create step record with parentStepId and parallel
                 const newStep = await this.#stepStore.getOrCreate(this.#jobId, name, expire, retryOptions.limit, parentStepId, parallel);
                 if (!newStep) {
                     throw new NonRetriableError(`Failed to create step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`, { cause: 'step not created' });
                 }
                 step = newStep;
+                // Start step span - uses no-op tracer if no SDK is configured
                 const parentSpan = parentStepId ? this.#stepSpans.get(parentStepId) : this.#jobSpan;
-                const stepSpan = await this.#telemetry.startStepSpan({
-                    jobId: this.#jobId,
-                    stepId: step.id,
-                    stepName: name,
-                    parentSpan: parentSpan ?? undefined,
-                    parentStepId,
-                });
+                const parentContext = parentSpan ? trace.setSpan(context.active(), parentSpan) : context.active();
+                const stepSpan = this.#tracer.startSpan(`step:${name}`, {
+                    kind: SpanKind.INTERNAL,
+                    attributes: {
+                        'duron.job.id': this.#jobId,
+                        'duron.step.id': step.id,
+                        'duron.step.name': name,
+                        'duron.step.parent_id': parentStepId ?? undefined,
+                    },
+                }, parentContext);
                 this.#stepSpans.set(step.id, stepSpan);
                 if (abortSignal.aborted) {
                     throw new ActionCancelError(this.#actionName, this.#jobId, { cause: 'step cancelled after create step' });
                 }
                 if (step.status === STEP_STATUS_COMPLETED) {
+                    // this is how we recover a completed step
                     this.#logger.debug({ jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id, parentStepId }, '[StepManager] Step recovered (already completed)');
                     return step.output;
                 }
@@ -175,59 +337,81 @@ export class StepManager {
                 else if (step.status === STEP_STATUS_CANCELLED) {
                     throw new NonRetriableError(`Cannot recover a cancelled step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`, { cause: step.error });
                 }
+                // Log step start
                 this.#logger.debug({ jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id, parentStepId }, '[StepManager] Step started executing');
             }
+            // Create abort controller for this step's timeout
             const stepAbortController = new AbortController();
             const timeoutId = setTimeout(() => {
-                const timeoutError = new StepTimeoutError(name, this.#jobId, expire);
+                const timeoutError = new StepTimeoutError(name, this.#jobId, expire, {
+                    stepId: step?.id,
+                    parentStepId,
+                    actionName: this.#actionName,
+                });
                 stepAbortController.abort(timeoutError);
             }, expire);
             timeoutId?.unref?.();
+            // Combine abort signals: parent chain + this step's timeout
             const stepSignal = AbortSignal.any([abortSignal, stepAbortController.signal]);
             const childSteps = [];
+            // Create abort controller for child steps (used when parent returns with pending children)
             const childAbortController = new AbortController();
             const childSignal = AbortSignal.any([stepSignal, childAbortController.signal]);
-            const stepObserveContext = this.createStepObserveContext(step.id);
+            // Create telemetry context for this step
+            const stepTelemetryContext = this.createStepTelemetryContext(step.id);
+            // Create StepHandlerContext with nested step support
             const stepContext = {
                 signal: stepSignal,
                 stepId: step.id,
                 parentStepId,
-                observe: stepObserveContext,
+                telemetry: stepTelemetryContext,
                 step: (childName, childCb, childOptions = {}) => {
+                    // Inherit parent step options EXCEPT parallel (each step's parallel status is independent)
                     const { parallel: _parentParallel, ...inheritableOptions } = options;
                     const parsedChildOptions = StepOptionsSchema.parse({
                         ...inheritableOptions,
                         ...childOptions,
                     });
+                    // Push child step with this step as parent
                     const childPromise = this.push({
                         name: childName,
                         cb: childCb,
                         options: parsedChildOptions,
-                        abortSignal: childSignal,
-                        parentStepId: step.id,
-                        parallel: parsedChildOptions.parallel,
+                        abortSignal: childSignal, // Child uses composed signal
+                        parentStepId: step.id, // This step is the parent
+                        parallel: parsedChildOptions.parallel, // Pass parallel option
                     });
+                    // Track the child promise
                     const trackedChild = {
                         promise: childPromise,
                         settled: false,
                     };
                     childSteps.push(trackedChild);
+                    // Mark as settled when done (success or failure)
+                    // Use .then/.catch instead of .finally to properly handle rejections
                     childPromise
                         .then(() => {
                         trackedChild.settled = true;
                     })
                         .catch(() => {
                         trackedChild.settled = true;
+                        // Swallow the error here - it will be re-thrown to the caller via the returned promise
+                        // Note: sibling steps will be aborted when the error propagates to the action level
                     });
                     return childPromise;
                 },
                 run: this.#runFnFactory(step.id, childSignal),
             };
             try {
+                // Race between abort signal and callback execution
                 const abortPromise = waitForAbort(stepSignal);
-                const callbackPromise = cb(stepContext);
+                // Execute callback within the span context so that child spans inherit the trace
+                const currentStepSpan = step?.id ? this.#stepSpans.get(step.id) : undefined;
+                const spanContext = currentStepSpan ? trace.setSpan(context.active(), currentStepSpan) : context.active();
+                const callbackPromise = context.with(spanContext, () => cb(stepContext));
                 let result = null;
                 let aborted = false;
+                let callbackError = null;
                 await Promise.race([
                     abortPromise.promise.then(() => {
                         aborted = true;
@@ -237,17 +421,34 @@ export class StepManager {
                         if (res !== undefined && res !== null) {
                             result = res;
                         }
+                    })
+                        .catch((err) => {
+                        callbackError = err;
                     })
                         .finally(() => {
                         abortPromise.release();
                     }),
                 ]);
+                // If callback threw an error, abort children and wait for them before re-throwing
+                if (callbackError) {
+                    if (childSteps.length > 0) {
+                        // Abort all children with the callback error as reason
+                        childAbortController.abort(callbackError);
+                        // Wait for all children to settle
+                        await Promise.allSettled(childSteps.map((c) => c.promise));
+                    }
+                    throw callbackError;
+                }
+                // If aborted, wait for child steps to settle before propagating
                 if (aborted) {
+                    // Wait for all child steps to settle (they'll be aborted via signal propagation)
                     if (childSteps.length > 0) {
                         await Promise.allSettled(childSteps.map((c) => c.promise));
                     }
+                    // Re-throw the abort reason
                     throw stepSignal.reason;
                 }
+                // After parent callback returns, check for pending children
                 const unsettledChildren = childSteps.filter((c) => !c.settled);
                 if (unsettledChildren.length > 0) {
                     this.#logger.warn({
@@ -257,20 +458,32 @@ export class StepManager {
                         stepId: step.id,
                         pendingCount: unsettledChildren.length,
                     }, '[StepManager] Parent step completed with unhandled child steps - aborting children');
-                    const unhandledError = new UnhandledChildStepsError(name, unsettledChildren.length);
+                    // Abort all pending children
+                    const unhandledError = new UnhandledChildStepsError(name, unsettledChildren.length, {
+                        stepId: step.id,
+                        parentStepId,
+                        jobId: this.#jobId,
+                        actionName: this.#actionName,
+                    });
                     childAbortController.abort(unhandledError);
+                    // Wait for all children to settle (they'll reject with cancellation)
                     await Promise.allSettled(unsettledChildren.map((c) => c.promise));
+                    // Now throw the error
                     throw unhandledError;
                 }
+                // Update step as completed
                 const completed = await this.#stepStore.updateStatus(step.id, 'completed', result);
                 if (!completed) {
                     throw new Error(`Failed to complete step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`);
                 }
+                // End step span successfully
                 const stepSpan = this.#stepSpans.get(step.id);
                 if (stepSpan) {
-                    await this.#telemetry.endStepSpan(stepSpan, { status: 'ok' });
+                    stepSpan.setStatus({ code: SpanStatusCode.OK });
+                    stepSpan.end();
                     this.#stepSpans.delete(step.id);
                 }
+                // Log step completion
                 this.#logger.debug({ jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id }, '[StepManager] Step finished executing');
                 return result;
             }
@@ -278,6 +491,7 @@ export class StepManager {
                 clearTimeout(timeoutId);
             }
         };
+        // Apply retry logic - skip retries for NonRetriableError
         return pRetry(executeStep, {
             retries: retryOptions.limit,
             factor: retryOptions.factor,
@@ -287,28 +501,67 @@ export class StepManager {
             maxTimeout: retryOptions.maxTimeout,
             onFailedAttempt: async (ctx) => {
                 const error = ctx.error;
+                // Don't retry if error is non-retriable
                 if (isNonRetriableError(error) ||
                     (error.cause && isNonRetriableError(error.cause)) ||
-                    (error instanceof Error && error.name === 'AbortError' && isNonRetriableError(error.cause))) {
-                    throw error;
+                    (error instanceof Error && error.name === 'AbortError')) {
+                    const err = isNonRetriableError(error)
+                        ? error
+                        : error instanceof Error && error.name === 'AbortError'
+                            ? new NonRetriableError(error.message, { cause: error.cause })
+                            : error.cause;
+                    if (Object.keys(err.metadata).length === 0) {
+                        err.setMetadata({
+                            stepId: step?.id,
+                            parentStepId,
+                            jobId: this.#jobId,
+                            actionName: this.#actionName,
+                        });
+                    }
+                    throw err;
                 }
                 if (ctx.retriesLeft > 0 && step) {
+                    this.#clearHistoryForStep(step.id);
                     const delayed = await this.#stepStore.delay(step.id, ctx.finalDelay, serializeError(error));
                     if (!delayed) {
                         throw new Error(`Failed to delay step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`);
                     }
                 }
+                else {
+                    if (isTimeoutError(error)) {
+                        ;
+                        error.nonRetriable = true;
+                        throw error;
+                    }
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    const err = new NonRetriableError(errorMessage, { cause: error });
+                    err.setMetadata({
+                        stepId: step?.id,
+                        parentStepId,
+                        jobId: this.#jobId,
+                        actionName: this.#actionName,
+                    });
+                    throw err;
+                }
             },
         }).catch(async (error) => {
             if (step) {
+                // End step span with error/cancelled status
                 const stepSpan = this.#stepSpans.get(step.id);
                 if (stepSpan) {
                     if (isCancelError(error)) {
-                        await this.#telemetry.endStepSpan(stepSpan, { status: 'cancelled' });
+                        stepSpan.setStatus({ code: SpanStatusCode.ERROR, message: 'Step cancelled' });
                     }
                     else {
-                        await this.#telemetry.endStepSpan(stepSpan, { status: 'error', error });
+                        stepSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                        if (error instanceof Error) {
+                            stepSpan.recordException(error);
+                        }
                     }
+                    stepSpan.end();
                     this.#stepSpans.delete(step.id);
                 }
                 if (isCancelError(error)) {
@@ -321,7 +574,26 @@ export class StepManager {
             throw error;
         });
     }
+    /**
+     * Clear the history of nested steps for a given step.
+     * We do't need to clear the history for the root step because it's not a parent step, it's the action itself.
+     * @param stepId - The ID of the step to clear the history for
+     */
+    #clearHistoryForStep(stepId) {
+        this.#historySteps.forEach((stepKey) => {
+            if (stepKey.startsWith(stepId)) {
+                this.#historySteps.delete(stepKey);
+            }
+        });
+    }
 }
+// ============================================================================
+// ActionContext Class
+// ============================================================================
+/**
+ * ActionContext provides the context for action handlers.
+ * It implements ActionHandlerContext and provides access to input, variables, logger, and the step function.
+ */
 class ActionContext {
     #stepManager;
     #variables;
@@ -331,8 +603,11 @@ class ActionContext {
     #jobId;
     #groupKey = '@default';
     #action;
-    #observeContext;
-    constructor(stepManager, job, action, variables, abortSignal, logger, observeContext) {
+    #telemetryContext;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    constructor(stepManager, job, action, variables, abortSignal, logger, telemetryContext) {
         this.#stepManager = stepManager;
         this.#variables = variables;
         this.#abortSignal = abortSignal;
@@ -340,7 +615,7 @@ class ActionContext {
         this.#action = action;
         this.#jobId = job.id;
         this.#groupKey = job.groupKey ?? '@default';
-        this.#observeContext = observeContext;
+        this.#telemetryContext = telemetryContext;
         if (action.input) {
             this.#input = action.input.parse(job.input, {
                 error: () => 'Error parsing action input',
@@ -350,28 +625,63 @@ class ActionContext {
         this.#input = job.input ?? {};
         this.step = this.step.bind(this);
         this.run = this.run.bind(this);
+        // Set the run function factory so inline steps can call step definitions with correct parent
         this.#stepManager.setRunFnFactory((parentStepId, abortSignal) => {
             return (stepDef, input, options) => this.#runInternal(stepDef, input, options, parentStepId, abortSignal);
         });
     }
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
+    /**
+     * Get the input data for this action.
+     */
     get input() {
         return this.#input;
     }
+    /**
+     * Get the job ID for this action context.
+     *
+     * @returns The job ID
+     */
     get jobId() {
         return this.#jobId;
     }
+    /**
+     * Get the group key for this action context.
+     *
+     * @returns The group key
+     */
     get groupKey() {
         return this.#groupKey;
     }
+    /**
+     * Get the variables available to this action.
+     */
     get var() {
         return this.#variables;
     }
+    /**
+     * Get the logger for this action job.
+     */
     get logger() {
         return this.#logger;
     }
-    get observe() {
-        return this.#observeContext;
+    /**
+     * Get the telemetry context for recording metrics and span data.
+     */
+    get telemetry() {
+        return this.#telemetryContext;
     }
+    /**
+     * Execute a step within the action.
+     * This creates a root step (no parent).
+     *
+     * @param name - The name of the step
+     * @param cb - The step handler function
+     * @param options - Optional step options (will be merged with defaults)
+     * @returns Promise resolving to the step result
+     */
     async step(name, cb, options = {}) {
         const parsedOptions = StepOptionsSchema.parse({
             ...this.#action.steps,
@@ -382,21 +692,46 @@ class ActionContext {
             cb,
             options: parsedOptions,
             abortSignal: this.#abortSignal,
-            parentStepId: null,
-            parallel: parsedOptions.parallel,
+            parentStepId: null, // Root steps have no parent
+            parallel: parsedOptions.parallel, // Pass parallel option
         });
     }
+    /**
+     * Execute a reusable step definition created with createStep().
+     * This is the public method called from action handlers.
+     *
+     * @param stepDef - The step definition to execute
+     * @param input - The input data for the step (validated against the step's input schema)
+     * @param options - Optional step configuration overrides
+     * @returns Promise resolving to the step result
+     */
     async run(stepDef, input, options = {}) {
         return this.#runInternal(stepDef, input, options, null, this.#abortSignal);
     }
+    /**
+     * Internal method to execute a step definition with explicit parent step ID and abort signal.
+     * Used by both the public run method and the run functions passed to step contexts.
+     */
     async #runInternal(stepDef, input, options = {}, parentStepId, abortSignal) {
+        // Validate input against the step's schema if provided
+        // After parsing, validatedInput is z.output<TStepInput> (same as z.infer<TStepInput>)
         const validatedInput = stepDef.input
             ? stepDef.input.parse(input, {
                 error: () => 'Error parsing step input',
                 reportInput: true,
             })
             : input;
-        const stepName = typeof stepDef.name === 'function' ? stepDef.name({ input: validatedInput }) : stepDef.name;
+        // Resolve step name (static or dynamic)
+        // If it's a function, pass the full context including input, variables, jobId, and parentStepId
+        const stepName = typeof stepDef.name === 'function'
+            ? stepDef.name({
+                input: validatedInput,
+                var: this.#variables,
+                jobId: this.#jobId,
+                parentStepId,
+            })
+            : stepDef.name;
+        // Merge options: action defaults -> step definition -> call-time overrides
         const mergedOptions = {
             ...this.#action.steps,
             ...(stepDef.retry !== undefined && { retry: stepDef.retry }),
@@ -405,6 +740,7 @@ class ActionContext {
             ...options,
         };
         const parsedOptions = StepOptionsSchema.parse(mergedOptions);
+        // Create a wrapper callback that provides the extended context
         const wrappedCb = async (baseCtx) => {
             const extendedCtx = {
                 ...baseCtx,