duron 0.3.0-beta.0 → 0.3.0-beta.10

package/src/step-manager.ts

@@ -5,6 +5,8 @@ import type { z } from 'zod'
 import {
   type Action,
   type ActionHandlerContext,
+  type StepDefinition,
+  type StepDefinitionHandlerContext,
   type StepHandlerContext,
   type StepOptions,
   StepOptionsSchema,
@@ -15,13 +17,53 @@ import {
   ActionCancelError,
   isCancelError,
   isNonRetriableError,
+  isTimeoutError,
   NonRetriableError,
   StepAlreadyExecutedError,
   StepTimeoutError,
   serializeError,
   UnhandledChildStepsError,
 } from './errors.js'
-import type { ObserveContext, Span, TelemetryAdapter } from './telemetry/adapter.js'
+import type { ObserveContext, Span, TelemetryAdapter, Tracer, TracerSpan } from './telemetry/adapter.js'
+
+// ============================================================================
+// Noop Tracer (for fallback observe context)
+// ============================================================================
+
+const noopTracerSpan: TracerSpan = {
+  setAttribute() {
+    // No-op
+  },
+  setAttributes() {
+    // No-op
+  },
+  addEvent() {
+    // No-op
+  },
+  recordException() {
+    // No-op
+  },
+  setStatusOk() {
+    // No-op
+  },
+  setStatusError() {
+    // No-op
+  },
+  end() {
+    // No-op
+  },
+  isRecording() {
+    return false
+  },
+}
+
+const createNoopTracer = (name: string): Tracer => ({
+  name,
+  startSpan(): TracerSpan {
+    return noopTracerSpan
+  },
+})
+
 import pRetry from './utils/p-retry.js'
 import waitForAbort from './utils/wait-for-abort.js'
 
@@ -146,12 +188,14 @@ export class StepManager {
   #telemetry: TelemetryAdapter
   #queue: fastq.queueAsPromised<TaskStep, any>
   #logger: Logger
-  // each step name should be executed only once per action job
+  // each step name should be executed only once per parent (name + parentStepId)
   #historySteps = new Set<string>()
   // Store step spans for nested step tracking
   #stepSpans = new Map<string, Span>()
   // Store the job span for creating step spans
   #jobSpan: Span | null = null
+  // Factory function to create run functions with the correct parent step ID and abort signal
+  #runFnFactory: ((parentStepId: string | null, abortSignal: AbortSignal) => StepHandlerContext['run']) | null = null
 
   // ============================================================================
   // Constructor
@@ -169,10 +213,12 @@ export class StepManager {
     this.#telemetry = options.telemetry
     this.#stepStore = new StepStore(options.adapter)
     this.#queue = fastq.promise(async (task: TaskStep) => {
-      if (this.#historySteps.has(task.name)) {
+      // 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)
       }
-      this.#historySteps.add(task.name)
+      this.#historySteps.add(stepKey)
       return this.#executeStep(task.name, task.cb, task.options, task.abortSignal, task.parentStepId, task.parallel)
     }, options.concurrencyLimit)
   }
@@ -185,6 +231,16 @@ export class StepManager {
     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: (parentStepId: string | null, abortSignal: AbortSignal) => StepHandlerContext['run']): void {
+    this.#runFnFactory = factory
+  }
+
   // ============================================================================
   // Public API Methods
   // ============================================================================
@@ -235,6 +291,9 @@ export class StepManager {
       addSpanEvent: () => {
         // No-op
       },
+      getTracer: (name: string) => {
+        return createNoopTracer(name)
+      },
     }
   }
 
@@ -245,6 +304,21 @@ export class StepManager {
    * @returns Promise resolving to the step result
    */
   async push(task: TaskStep): Promise<any> {
+    // 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,
+          actionName: this.#actionName,
+          stepName: task.name,
+          parentStepId: task.parentStepId,
+          running: this.#queue.running(),
+          waiting: this.#queue.length(),
+          concurrency: this.#queue.concurrency,
+        },
+        '[StepManager] Potential starvation: child step queued while all concurrency slots are occupied by parent steps. Consider increasing steps.concurrency.',
+      )
+    }
     return this.#queue.push(task)
   }
 
@@ -353,7 +427,11 @@ export class StepManager {
       // 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)
 
@@ -420,10 +498,12 @@ export class StepManager {
             .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 {
@@ -433,6 +513,7 @@ export class StepManager {
 
         let result: any = null
         let aborted = false
+        let callbackError: Error | null = null
 
         await Promise.race([
           abortPromise.promise.then(() => {
@@ -444,11 +525,25 @@ export class StepManager {
                 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)
@@ -474,7 +569,12 @@ export class StepManager {
           )
 
           // Abort all pending children
-          const unhandledError = new UnhandledChildStepsError(name, unsettledChildren.length)
+          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)
@@ -523,16 +623,46 @@ export class StepManager {
         if (
           isNonRetriableError(error) ||
           (error.cause && isNonRetriableError(error.cause)) ||
-          (error instanceof Error && error.name === 'AbortError' && isNonRetriableError(error.cause))
+          (error instanceof Error && error.name === 'AbortError')
         ) {
-          throw error
+          const err = isNonRetriableError(error)
+            ? error
+            : error instanceof Error && error.name === 'AbortError'
+              ? new NonRetriableError(error.message, { cause: error.cause })
+              : (error.cause as NonRetriableError)
+
+          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 as any).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) => {
@@ -557,6 +687,19 @@ 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: string): void {
+    this.#historySteps.forEach((stepKey) => {
+      if (stepKey.startsWith(stepId)) {
+        this.#historySteps.delete(stepKey)
+      }
+    })
+  }
 }
 
 // ============================================================================
@@ -609,6 +752,11 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
     }
     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)
+    })
   }
 
   // ============================================================================
@@ -679,6 +827,7 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
       ...this.#action.steps,
       ...options,
     })
+
     return this.#stepManager.push({
       name,
       cb,
@@ -688,4 +837,77 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
       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<TStepInput extends z.ZodObject, TResult>(
+    stepDef: StepDefinition<TStepInput, TResult, TVariables>,
+    input: z.input<TStepInput>,
+    options: Partial<z.input<typeof StepOptionsSchema>> = {},
+  ): Promise<TResult> {
+    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<TStepInput extends z.ZodObject, TResult>(
+    stepDef: StepDefinition<TStepInput, TResult, TVariables>,
+    input: z.input<TStepInput>,
+    options: Partial<z.input<typeof StepOptionsSchema>> = {},
+    parentStepId: string | null,
+    abortSignal: AbortSignal,
+  ): Promise<TResult> {
+    // Validate input against the step's schema if provided
+    // After parsing, validatedInput is z.output<TStepInput> (same as z.infer<TStepInput>)
+    const validatedInput: z.infer<TStepInput> = stepDef.input
+      ? stepDef.input.parse(input, {
+          error: () => 'Error parsing step input',
+          reportInput: true,
+        })
+      : (input as z.infer<TStepInput>)
+
+    // Resolve step name (static or dynamic)
+    const stepName = typeof stepDef.name === 'function' ? stepDef.name({ input: validatedInput }) : stepDef.name
+
+    // Merge options: action defaults -> step definition -> call-time overrides
+    const mergedOptions: z.input<typeof StepOptionsSchema> = {
+      ...this.#action.steps,
+      ...(stepDef.retry !== undefined && { retry: stepDef.retry }),
+      ...(stepDef.expire !== undefined && { expire: stepDef.expire }),
+      ...(stepDef.parallel !== undefined && { parallel: stepDef.parallel }),
+      ...options,
+    }
+
+    const parsedOptions = StepOptionsSchema.parse(mergedOptions)
+
+    // Create a wrapper callback that provides the extended context
+    const wrappedCb = async (baseCtx: StepHandlerContext): Promise<TResult> => {
+      const extendedCtx: StepDefinitionHandlerContext<TStepInput, TVariables> = {
+        ...baseCtx,
+        input: validatedInput,
+        var: this.#variables,
+        logger: this.#logger,
+        jobId: this.#jobId,
+      }
+      return stepDef.handler(extendedCtx)
+    }
+
+    return this.#stepManager.push({
+      name: stepName,
+      cb: wrappedCb,
+      options: parsedOptions,
+      abortSignal,
+      parentStepId,
+      parallel: parsedOptions.parallel,
+    })
+  }
 }

package/src/telemetry/adapter.ts

@@ -108,6 +108,106 @@ export interface AddSpanAttributeOptions {
   value: string | number | boolean
 }
 
+/**
+ * Options for starting a custom span with the tracer.
+ */
+export interface StartSpanOptions {
+  /**
+   * Span kind (internal, client, server, producer, consumer).
+   * @default 'internal'
+   */
+  kind?: 'internal' | 'client' | 'server' | 'producer' | 'consumer'
+
+  /**
+   * Initial attributes for the span.
+   */
+  attributes?: Record<string, string | number | boolean>
+
+  /**
+   * Parent span to use for context propagation.
+   * If not provided, uses the current active context.
+   */
+  parentSpan?: TracerSpan
+}
+
+/**
+ * A span created by the Tracer for manual instrumentation.
+ */
+export interface TracerSpan {
+  /**
+   * Set an attribute on the span.
+   *
+   * @param key - The attribute key
+   * @param value - The attribute value
+   */
+  setAttribute(key: string, value: string | number | boolean): void
+
+  /**
+   * Set multiple attributes on the span.
+   *
+   * @param attributes - The attributes to set
+   */
+  setAttributes(attributes: Record<string, string | number | boolean>): void
+
+  /**
+   * Add an event to the span.
+   *
+   * @param name - The event name
+   * @param attributes - Optional event attributes
+   */
+  addEvent(name: string, attributes?: Record<string, string | number | boolean>): void
+
+  /**
+   * Record an exception on the span.
+   *
+   * @param error - The error to record
+   */
+  recordException(error: Error): void
+
+  /**
+   * Set the span status to OK.
+   */
+  setStatusOk(): void
+
+  /**
+   * Set the span status to error.
+   *
+   * @param message - Optional error message
+   */
+  setStatusError(message?: string): void
+
+  /**
+   * End the span.
+   * After calling this, no more operations can be performed on the span.
+   */
+  end(): void
+
+  /**
+   * Check if this span is recording.
+   */
+  isRecording(): boolean
+}
+
+/**
+ * A Tracer provides methods for creating spans.
+ * Similar to OpenTelemetry's Tracer interface.
+ */
+export interface Tracer {
+  /**
+   * The name of this tracer.
+   */
+  readonly name: string
+
+  /**
+   * Start a new span.
+   *
+   * @param name - The name of the span
+   * @param options - Optional span configuration
+   * @returns A TracerSpan for manual instrumentation
+   */
+  startSpan(name: string, options?: StartSpanOptions): TracerSpan
+}
+
 /**
  * Observe context provided to action and step handlers.
  */
@@ -136,6 +236,37 @@ export interface ObserveContext {
    * @param attributes - Optional event attributes
    */
   addSpanEvent(name: string, attributes?: Record<string, any>): void
+
+  /**
+   * Get a tracer for manual instrumentation.
+   * Similar to OpenTelemetry's `trace.getTracer()` method.
+   *
+   * @param name - The name of the tracer (typically your service or library name)
+   * @returns A Tracer for creating custom spans
+   *
+   * @example
+   * ```typescript
+   * const tracer = ctx.observe.getTracer('my-service')
+   *
+   * const span = tracer.startSpan('external-api-call', {
+   *   kind: 'client',
+   *   attributes: { 'api.endpoint': '/users' }
+   * })
+   *
+   * try {
+   *   const result = await fetch('https://api.example.com/users')
+   *   span.setStatusOk()
+   *   return result
+   * } catch (error) {
+   *   span.recordException(error)
+   *   span.setStatusError(error.message)
+   *   throw error
+   * } finally {
+   *   span.end()
+   * }
+   * ```
+   */
+  getTracer(name: string): Tracer
 }
 
 // ============================================================================
@@ -369,6 +500,41 @@ export abstract class TelemetryAdapter {
     return this._addSpanAttribute(options)
   }
 
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  /**
+   * Get a tracer for manual instrumentation.
+   * Similar to OpenTelemetry's `trace.getTracer()` method.
+   *
+   * @param name - The name of the tracer (typically your service or library name)
+   * @returns A Tracer for creating custom spans
+   *
+   * @example
+   * ```typescript
+   * const tracer = telemetry.getTracer('my-service')
+   *
+   * const span = tracer.startSpan('process-order', {
+   *   attributes: { 'order.id': orderId }
+   * })
+   *
+   * try {
+   *   // Do some work
+   *   span.addEvent('order.validated')
+   *   span.setStatusOk()
+   * } catch (error) {
+   *   span.recordException(error)
+   *   span.setStatusError(error.message)
+   * } finally {
+   *   span.end()
+   * }
+   * ```
+   */
+  getTracer(name: string): Tracer {
+    return this._getTracer(name)
+  }
+
   // ============================================================================
   // Context Methods
   // ============================================================================
@@ -404,6 +570,9 @@ export abstract class TelemetryAdapter {
           this.#logger?.error(err, 'Error adding span event')
         })
       },
+      getTracer: (name: string) => {
+        return this.getTracer(name)
+      },
     }
   }
 
@@ -465,4 +634,9 @@ export abstract class TelemetryAdapter {
    * Internal method to add a span attribute.
    */
   protected abstract _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>
+
+  /**
+   * Internal method to get a tracer for manual instrumentation.
+   */
+  protected abstract _getTracer(name: string): Tracer
 }

package/src/telemetry/index.ts

@@ -9,8 +9,11 @@ export {
   type Span,
   type StartDatabaseSpanOptions,
   type StartJobSpanOptions,
+  type StartSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 export { LocalTelemetryAdapter, type LocalTelemetryAdapterOptions, localTelemetryAdapter } from './local.js'
 export { NoopTelemetryAdapter, noopTelemetryAdapter } from './noop.js'

package/src/telemetry/local.ts

@@ -7,8 +7,11 @@ import {
   type Span,
   type StartDatabaseSpanOptions,
   type StartJobSpanOptions,
+  type StartSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 
 // ============================================================================
@@ -304,6 +307,96 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
       },
     })
   }
+
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  protected _getTracer(name: string): Tracer {
+    const adapter = this
+
+    return {
+      name,
+
+      startSpan(spanName: string, options?: StartSpanOptions): TracerSpan {
+        const spanId = `tracer:${name}:${globalThis.crypto.randomUUID()}`
+        const startTime = Date.now()
+        let ended = false
+        const attributes: Record<string, string | number | boolean> = {
+          ...options?.attributes,
+        }
+
+        // Note: Local adapter tracer spans don't have a jobId context,
+        // so they can't be stored in the database. They're essentially no-ops
+        // but provide a consistent API for code that needs a tracer.
+        // For actual metrics storage, use ctx.observe within action/step handlers.
+
+        const tracerSpan: TracerSpan = {
+          setAttribute(key: string, value: string | number | boolean): void {
+            if (!ended) {
+              attributes[key] = value
+            }
+          },
+
+          setAttributes(attrs: Record<string, string | number | boolean>): void {
+            if (!ended) {
+              Object.assign(attributes, attrs)
+            }
+          },
+
+          addEvent(eventName: string, eventAttrs?: Record<string, string | number | boolean>): void {
+            if (!ended) {
+              adapter.logger?.debug({ spanId, event: eventName, attributes: eventAttrs }, 'Tracer span event')
+            }
+          },
+
+          recordException(error: Error): void {
+            if (!ended) {
+              attributes['error.message'] = error.message
+              attributes['error.name'] = error.name
+              adapter.logger?.debug({ spanId, error: error.message }, 'Tracer span exception')
+            }
+          },
+
+          setStatusOk(): void {
+            if (!ended) {
+              // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
+              attributes['status'] = 'ok'
+            }
+          },
+
+          setStatusError(message?: string): void {
+            if (!ended) {
+              // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
+              attributes['status'] = 'error'
+              if (message) {
+                attributes['status.message'] = message
+              }
+            }
+          },
+
+          end(): void {
+            if (!ended) {
+              ended = true
+              const duration = Date.now() - startTime
+              adapter.logger?.debug(
+                { spanId, spanName, tracerName: name, durationMs: duration, attributes },
+                'Tracer span ended',
+              )
+            }
+          },
+
+          isRecording(): boolean {
+            return !ended
+          },
+        }
+
+        adapter.logger?.debug({ spanId, spanName, tracerName: name }, 'Tracer span started')
+
+        return tracerSpan
+      },
+    }
+  }
 }
 
 /**