duron 0.3.0-beta.8 → 0.3.0

package/dist/client.js

@@ -1,9 +1,14 @@
+import { trace } from '@opentelemetry/api';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
 import pino, {} from 'pino';
 import { zocker } from 'zocker';
 import * as z from 'zod';
 import { ActionManager } from './action-manager.js';
 import { JOB_STATUS_CANCELLED, JOB_STATUS_COMPLETED, JOB_STATUS_FAILED } from './constants.js';
-import { LocalTelemetryAdapter, noopTelemetryAdapter } from './telemetry/index.js';
+import { LocalSpanExporter } from './telemetry/local-span-exporter.js';
 const BaseOptionsSchema = z.object({
     id: z.string().optional(),
     syncPattern: z.union([z.literal('pull'), z.literal('push'), z.literal('hybrid'), z.literal(false)]).default('hybrid'),
@@ -16,12 +21,23 @@ const BaseOptionsSchema = z.object({
     multiProcessMode: z.boolean().default(false),
     processTimeout: z.number().default(5 * 1000),
 });
+const _checkOptions = true;
+/**
+ * Client is the main entry point for Duron.
+ * Manages job execution, action handling, and database operations.
+ *
+ * @template TActions - Record of action definitions keyed by action name
+ * @template TVariables - Type of variables available to actions
+ */
 export class Client {
     #options;
     #id;
     #actions;
     #database;
-    #telemetry;
+    #tracerProvider = null;
+    #tracer;
+    #telemetryOptions = null;
+    #localSpansEnabled = false;
     #variables;
     #logger;
     #started = false;
@@ -33,18 +49,68 @@ export class Client {
     #mockInputSchemas = new Map();
     #pendingJobWaits = new Map();
     #jobStatusListenerSetup = false;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new Duron Client instance.
+     *
+     * @param options - Configuration options for the client
+     */
     constructor(options) {
         this.#options = BaseOptionsSchema.parse(options);
         this.#id = options.id ?? globalThis.crypto.randomUUID();
         this.#database = options.database;
-        this.#telemetry = options.telemetry ?? noopTelemetryAdapter();
+        this.#telemetryOptions = options.telemetry ?? null;
         this.#actions = options.actions ?? null;
         this.#variables = options?.variables ?? {};
         this.#logger = this.#normalizeLogger(options?.logger);
         this.#database.setId(this.#id);
         this.#database.setLogger(this.#logger);
-        this.#telemetry.setLogger(this.#logger);
-        this.#telemetry.setClient(this);
+        // Initialize OpenTelemetry TracerProvider if telemetry options are provided
+        // When no options are provided, the tracer will be a no-op (from OpenTelemetry API)
+        if (this.#telemetryOptions) {
+            this.#initTelemetry(this.#telemetryOptions);
+        }
+        // Get tracer from our provider if configured, otherwise use global no-op tracer
+        // This keeps telemetry scoped to this client instance rather than globally registered
+        this.#tracer = this.#tracerProvider?.getTracer('duron') ?? trace.getTracer('duron');
+    }
+    /**
+     * Initialize OpenTelemetry TracerProvider with configured processors.
+     */
+    #initTelemetry(options) {
+        const serviceName = options.serviceName ?? 'duron';
+        const processors = [];
+        // Add local span exporter if enabled
+        if (options.local) {
+            const localOptions = typeof options.local === 'boolean' ? {} : options.local;
+            const flushDelayMs = localOptions.flushDelayMs ?? 5000;
+            const localExporter = new LocalSpanExporter({ adapter: this.#database });
+            processors.push(new BatchSpanProcessor(localExporter, {
+                scheduledDelayMillis: flushDelayMs,
+            }));
+            this.#localSpansEnabled = true;
+        }
+        // Add custom span processors
+        if (options.spanProcessors) {
+            processors.push(...options.spanProcessors);
+        }
+        // Add custom trace exporter wrapped in BatchSpanProcessor
+        if (options.traceExporter) {
+            processors.push(new BatchSpanProcessor(options.traceExporter));
+        }
+        // Only create TracerProvider if we have processors
+        if (processors.length > 0) {
+            this.#tracerProvider = new NodeTracerProvider({
+                resource: resourceFromAttributes({
+                    [ATTR_SERVICE_NAME]: serviceName,
+                }),
+                spanProcessors: processors,
+            });
+            // Note: We do NOT call .register() here to avoid global state pollution
+            // The tracer is obtained directly from this provider instance
+        }
     }
     #normalizeLogger(logger) {
         let pinoInstance = null;
@@ -59,18 +125,46 @@ export class Client {
         }
         return pinoInstance.child({ duron: this.#id });
     }
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
     get logger() {
         return this.#logger;
     }
-    get telemetry() {
-        return this.#telemetry;
+    /**
+     * Get the OpenTelemetry tracer for creating custom spans.
+     * Always returns a tracer - it's a no-op tracer when no SDK is configured.
+     */
+    get tracer() {
+        return this.#tracer;
     }
+    /**
+     * Get the database adapter instance.
+     */
     get database() {
         return this.#database;
     }
-    get metricsEnabled() {
-        return this.#telemetry instanceof LocalTelemetryAdapter;
-    }
+    /**
+     * Check if local span storage is enabled.
+     * Returns true if telemetry.local is enabled.
+     */
+    get spansEnabled() {
+        return this.#localSpansEnabled;
+    }
+    /**
+     * Force flush any pending telemetry data.
+     * Useful in tests or when you need to ensure spans are exported before querying.
+     */
+    async flushTelemetry() {
+        if (this.#tracerProvider) {
+            await this.#tracerProvider.forceFlush();
+        }
+    }
+    /**
+     * Get the current configuration of this Duron instance.
+     *
+     * @returns Configuration object including options, actions, and variables
+     */
     getConfig() {
         return {
             ...this.#options,
@@ -78,12 +172,21 @@ export class Client {
             variables: this.#variables,
         };
     }
+    /**
+     * Run an action by creating a new job.
+     *
+     * @param actionName - Name of the action to run
+     * @param input - Input data for the action (validated against action's input schema if provided)
+     * @returns Promise resolving to the created job ID
+     * @throws Error if action is not found or job creation fails
+     */
     async runAction(actionName, input) {
         await this.start();
         const action = this.#actions?.[actionName];
         if (!action) {
             throw new Error(`Action ${String(actionName)} not found`);
         }
+        // Validate input if schema is provided
         let validatedInput = input ?? {};
         if (action.input) {
             validatedInput = action.input.parse(validatedInput, {
@@ -91,6 +194,7 @@ export class Client {
                 reportInput: true,
             });
         }
+        // Determine groupKey and concurrency limit using concurrency handler or defaults
         const concurrencyCtx = {
             input: validatedInput,
             var: this.#variables,
@@ -103,6 +207,12 @@ export class Client {
         if (action.groups?.concurrency) {
             concurrencyLimit = await action.groups.concurrency(concurrencyCtx);
         }
+        // Calculate description if provided
+        let description = null;
+        if (action.description) {
+            description = await action.description(concurrencyCtx);
+        }
+        // Create job in database
         const jobId = await this.#database.createJob({
             queue: action.name,
             groupKey,
@@ -110,6 +220,8 @@ export class Client {
             timeoutMs: action.expire,
             checksum: action.checksum,
             concurrencyLimit,
+            concurrencyStepLimit: action.steps.concurrency,
+            description,
         });
         if (!jobId) {
             throw new Error(`Failed to create job for action ${String(actionName)}`);
@@ -117,11 +229,24 @@ export class Client {
         this.#logger.debug({ jobId, actionName: String(actionName), groupKey }, '[Duron] Action sent/created');
         return jobId;
     }
+    /**
+     * Run an action and wait for its completion.
+     * This is a convenience method that combines `runAction` and `waitForJob`.
+     *
+     * @param actionName - Name of the action to run
+     * @param input - Input data for the action (validated against action's input schema if provided)
+     * @param options - Options including abort signal and timeout
+     * @returns Promise resolving to the job result with typed input and output
+     * @throws Error if action is not found, job creation fails, job is cancelled, or operation is aborted
+     */
     async runActionAndWait(actionName, input, options) {
+        // Check if already aborted before starting
         if (options?.signal?.aborted) {
             throw new Error('Operation was aborted');
         }
+        // Create the job
         const jobId = await this.runAction(actionName, input);
+        // Set up abort handler to cancel the job if signal is aborted
         let abortHandler;
         if (options?.signal) {
             abortHandler = () => {
@@ -131,6 +256,7 @@ export class Client {
             };
             options.signal.addEventListener('abort', abortHandler, { once: true });
         }
+        // Set up timeout handler to cancel the job if timeout is reached
         let timeoutId;
         let timeoutAbortController;
         if (options?.timeout) {
@@ -143,6 +269,7 @@ export class Client {
             }, options.timeout);
         }
         try {
+            // Combine signals if both are provided
             let waitSignal;
             if (options?.signal && timeoutAbortController) {
                 waitSignal = AbortSignal.any([options.signal, timeoutAbortController.signal]);
@@ -153,13 +280,16 @@ export class Client {
             else if (timeoutAbortController) {
                 waitSignal = timeoutAbortController.signal;
             }
+            // Wait for the job to complete
             const job = await this.waitForJob(jobId, { signal: waitSignal });
+            // Clean up
             if (timeoutId) {
                 clearTimeout(timeoutId);
             }
             if (options?.signal && abortHandler) {
                 options.signal.removeEventListener('abort', abortHandler);
             }
+            // Handle null result (aborted or timed out)
             if (!job) {
                 if (options?.signal?.aborted) {
                     throw new Error('Operation was aborted');
@@ -169,6 +299,7 @@ export class Client {
                 }
                 throw new Error('Job not found');
             }
+            // Handle cancelled job
             if (job.status === JOB_STATUS_CANCELLED) {
                 if (options?.signal?.aborted) {
                     throw new Error('Operation was aborted');
@@ -178,6 +309,7 @@ export class Client {
                 }
                 throw new Error('Job was cancelled');
             }
+            // Handle failed job
             if (job.status === JOB_STATUS_FAILED) {
                 const errorMessage = job.error?.message ?? 'Job failed';
                 const error = new Error(errorMessage);
@@ -186,9 +318,11 @@ export class Client {
                 }
                 throw error;
             }
+            // Return the job result with typed input/output
             return job;
         }
         catch (err) {
+            // Clean up on error
             if (timeoutId) {
                 clearTimeout(timeoutId);
             }
@@ -198,19 +332,37 @@ export class Client {
             throw err;
         }
     }
-    async fetch(options) {
+    /**
+     * Fetch and process jobs from the database.
+     * Concurrency limits are determined from the latest job created for each groupKey.
+     *
+     * @param [options.batchSize] - Maximum number of jobs to fetch in this batch (defaults to `batchSize` from client options)
+     * @returns Promise resolving to the array of fetched jobs
+     */
+    async fetch(options = {}) {
         await this.start();
         if (!this.#actions) {
             return [];
         }
+        // Fetch jobs from each action's queue
+        // Concurrency limits are determined from the latest job created for each groupKey
         const jobs = await this.#database.fetch({
             batch: options.batchSize ?? this.#options.batchSize,
         });
+        // Process fetched jobs
         for (const job of jobs) {
             this.#executeJob(job);
         }
         return jobs;
     }
+    /**
+     * Cancel a job by its ID.
+     * If the job is currently being processed, it will be cancelled immediately.
+     * Otherwise, it will be cancelled in the database.
+     *
+     * @param jobId - The ID of the job to cancel
+     * @returns Promise resolving to `true` if cancelled, `false` otherwise
+     */
     async cancelJob(jobId) {
         await this.start();
         let cancelled = false;
@@ -221,52 +373,134 @@ export class Client {
             }
         }
         if (!cancelled) {
+            // If the job is not being processed, cancel it in the database
             await this.#database.cancelJob({ jobId });
         }
         return cancelled;
     }
+    /**
+     * Retry a failed job by creating a copy of it with status 'created' and cleared output/error.
+     *
+     * @param jobId - The ID of the job to retry
+     * @returns Promise resolving to the new job ID, or `null` if retry failed
+     */
     async retryJob(jobId) {
         await this.start();
         return this.#database.retryJob({ jobId });
     }
+    /**
+     * Time travel a job to restart from a specific step.
+     * The job must be in completed, failed, or cancelled status.
+     * Resets the job and ancestor steps to active status, deletes subsequent steps,
+     * and preserves completed parallel siblings.
+     *
+     * @param jobId - The ID of the job to time travel
+     * @param stepId - The ID of the step to restart from
+     * @returns Promise resolving to `true` if time travel succeeded, `false` otherwise
+     */
     async timeTravelJob(jobId, stepId) {
         await this.start();
         return this.#database.timeTravelJob({ jobId, stepId });
     }
+    /**
+     * Delete a job by its ID.
+     * Active jobs cannot be deleted.
+     *
+     * @param jobId - The ID of the job to delete
+     * @returns Promise resolving to `true` if deleted, `false` otherwise
+     */
     async deleteJob(jobId) {
         await this.start();
         return this.#database.deleteJob({ jobId });
     }
+    /**
+     * Delete multiple jobs using the same filters as getJobs.
+     * Active jobs cannot be deleted and will be excluded from deletion.
+     *
+     * @param options - Query options including filters (same as getJobs)
+     * @returns Promise resolving to the number of jobs deleted
+     */
     async deleteJobs(options) {
         await this.start();
         return this.#database.deleteJobs(options);
     }
+    // ============================================================================
+    // Query Methods
+    // ============================================================================
+    /**
+     * Get a job by its ID. Does not include step information.
+     *
+     * @param jobId - The ID of the job to retrieve
+     * @returns Promise resolving to the job, or `null` if not found
+     */
     async getJobById(jobId) {
         await this.start();
         return this.#database.getJobById(jobId);
     }
+    /**
+     * Get steps for a job with pagination and fuzzy search.
+     * Steps are always ordered by created_at ASC.
+     * Steps do not include output data.
+     *
+     * @param options - Query options including jobId, pagination, and search
+     * @returns Promise resolving to steps result with pagination info
+     */
     async getJobSteps(options) {
         await this.start();
         return this.#database.getJobSteps(options);
     }
+    /**
+     * Get jobs with pagination, filtering, and sorting.
+     * Does not include step information or job output.
+     *
+     * @param options - Query options including pagination, filters, and sort
+     * @returns Promise resolving to jobs result with pagination info
+     */
     async getJobs(options) {
         await this.start();
         return this.#database.getJobs(options);
     }
+    /**
+     * Get a step by its ID with all information.
+     *
+     * @param stepId - The ID of the step to retrieve
+     * @returns Promise resolving to the step, or `null` if not found
+     */
     async getJobStepById(stepId) {
         await this.start();
         return this.#database.getJobStepById(stepId);
     }
+    /**
+     * Get job status and updatedAt timestamp.
+     *
+     * @param jobId - The ID of the job
+     * @returns Promise resolving to job status result, or `null` if not found
+     */
     async getJobStatus(jobId) {
         await this.start();
         return this.#database.getJobStatus(jobId);
     }
+    /**
+     * Get job step status and updatedAt timestamp.
+     *
+     * @param stepId - The ID of the step
+     * @returns Promise resolving to step status result, or `null` if not found
+     */
     async getJobStepStatus(stepId) {
         await this.start();
         return this.#database.getJobStepStatus(stepId);
     }
+    /**
+     * Wait for a job to change status by subscribing to job-status-changed events.
+     * When the job status changes, the job result is returned.
+     *
+     * @param jobId - The ID of the job to wait for
+     * @param options - Optional configuration including timeout
+     * @returns Promise resolving to the job result when its status changes, or `null` if timeout
+     */
     async waitForJob(jobId, options) {
         await this.start();
+        // First, check if the job already exists and is in a terminal state
         const existingJobStatus = await this.getJobStatus(jobId);
         if (existingJobStatus) {
             const terminalStatuses = [JOB_STATUS_COMPLETED, JOB_STATUS_FAILED, JOB_STATUS_CANCELLED];
@@ -276,30 +510,35 @@ export class Client {
                     return null;
                 }
                 return {
-                    jobId: job.id,
+                    id: job.id,
                     actionName: job.actionName,
                     status: job.status,
                     groupKey: job.groupKey,
+                    description: job.description,
                     input: job.input,
                     output: job.output,
                     error: job.error,
                 };
             }
         }
+        // Set up the shared event listener if not already set up
         this.#setupJobStatusListener();
         return new Promise((resolve) => {
+            // Check if already aborted before setting up wait
             if (options?.signal?.aborted) {
                 resolve(null);
                 return;
             }
             let timeoutId;
             let abortHandler;
+            // Set up timeout if provided
             if (options?.timeout) {
                 timeoutId = setTimeout(() => {
                     this.#removeJobWait(jobId, resolve);
                     resolve(null);
                 }, options.timeout);
             }
+            // Set up abort signal if provided
             if (options?.signal) {
                 abortHandler = () => {
                     this.#removeJobWait(jobId, resolve);
@@ -307,6 +546,7 @@ export class Client {
                 };
                 options.signal.addEventListener('abort', abortHandler);
             }
+            // Add this wait request to the pending waits
             if (!this.#pendingJobWaits.has(jobId)) {
                 this.#pendingJobWaits.set(jobId, new Set());
             }
@@ -318,17 +558,36 @@ export class Client {
             });
         });
     }
+    /**
+     * Get action statistics including counts and last job created date.
+     *
+     * @returns Promise resolving to action statistics
+     */
     async getActions() {
         await this.start();
         return this.#database.getActions();
     }
-    async getMetrics(options) {
+    /**
+     * Get spans for a job or step.
+     * Only available when telemetry.local is enabled.
+     *
+     * @param options - Query options including jobId/stepId, filters, and sort
+     * @returns Promise resolving to spans result
+     * @throws Error if local telemetry is not enabled
+     */
+    async getSpans(options) {
         await this.start();
-        if (!this.metricsEnabled) {
-            throw new Error('Metrics are only available when using LocalTelemetryAdapter');
+        if (!this.spansEnabled) {
+            throw new Error('Spans are only available when telemetry.local is enabled');
         }
-        return this.#database.getMetrics(options);
+        return this.#database.getSpans(options);
     }
+    /**
+     * Get action metadata including input schemas and mock data.
+     * This is useful for generating UI forms or mock data.
+     *
+     * @returns Promise resolving to action metadata
+     */
     async getActionsMetadata() {
         await this.start();
         if (!this.#actions) {
@@ -340,6 +599,39 @@ export class Client {
                 if (!this.#mockInputSchemas.has(action.name)) {
                     this.#mockInputSchemas.set(action.name, zocker(action.input)
                         .override(z.ZodString, 'string')
+                        .override(z.ZodBigInt, '4000') // Convert BigInt to string for JSON serialization
+                        .override(z.ZodNumber, (schema, _ctx) => {
+                        const greaterThan = schema.def.checks?.find((check) => check._zod.def.check === 'greater_than')?._zod
+                            .def;
+                        const lessThan = schema.def.checks?.find((check) => check._zod.def.check === 'less_than')?._zod
+                            .def;
+                        if (greaterThan && lessThan) {
+                            const min = greaterThan.inclusive ? greaterThan.value : greaterThan.value + 1;
+                            // For inclusive lessThan, we want to include the value, so max should be value + 1
+                            // For exclusive lessThan, we want to exclude the value, so max is the value itself
+                            const max = lessThan.inclusive ? lessThan.value + 1 : lessThan.value;
+                            // Ensure min < max
+                            if (min >= max) {
+                                return Math.floor(min);
+                            }
+                            return Math.floor(Math.random() * (max - min) + min);
+                        }
+                        if (greaterThan) {
+                            const min = greaterThan.inclusive ? greaterThan.value : greaterThan.value + 1;
+                            const max = min + 1000; // Use 1000 as default range
+                            return Math.floor(Math.random() * (max - min) + min);
+                        }
+                        if (lessThan) {
+                            // For inclusive lessThan, we want to include the value, so max should be value + 1
+                            // For exclusive lessThan, we want to exclude the value, so max is the value itself
+                            const max = lessThan.inclusive ? lessThan.value + 1 : lessThan.value;
+                            return Math.floor(Math.random() * max);
+                        }
+                        return Math.floor(Math.random() * 1000);
+                    })
+                        .number({
+                        extreme_value_chance: 0.01,
+                    })
                         .generate());
                 }
                 mockInput = this.#mockInputSchemas.get(action.name);
@@ -350,6 +642,15 @@ export class Client {
             };
         });
     }
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
+    /**
+     * Start the Duron instance.
+     * Initializes the database, recovers stuck jobs, and sets up sync patterns.
+     *
+     * @returns Promise resolving to `true` if started successfully, `false` otherwise
+     */
     async start() {
         if (this.#stopping || this.#stopped) {
             return false;
@@ -365,7 +666,6 @@ export class Client {
             if (!dbStarted) {
                 return false;
             }
-            await this.#telemetry.start();
             if (this.#actions) {
                 if (this.#options.recoverJobsOnStart) {
                     await this.#database.recoverJobs({
@@ -374,6 +674,7 @@ export class Client {
                         processTimeout: this.#options.processTimeout,
                     });
                 }
+                // Setup sync pattern
                 if (this.#options.syncPattern === 'pull' || this.#options.syncPattern === 'hybrid') {
                     this.#startPullLoop();
                 }
@@ -387,6 +688,12 @@ export class Client {
         })();
         return this.#starting;
     }
+    /**
+     * Stop the Duron instance.
+     * Stops the pull loop, aborts all running jobs, waits for queues to drain, and stops the database.
+     *
+     * @returns Promise resolving to `true` if stopped successfully, `false` otherwise
+     */
     async stop() {
         if (this.#stopped) {
             return true;
@@ -395,10 +702,12 @@ export class Client {
             return this.#stopping;
         }
         this.#stopping = (async () => {
+            // Stop pull loop
             if (this.#pullInterval) {
                 clearTimeout(this.#pullInterval);
                 this.#pullInterval = null;
             }
+            // Clean up all pending job waits
             for (const waits of this.#pendingJobWaits.values()) {
                 for (const wait of waits) {
                     if (wait.timeoutId) {
@@ -411,10 +720,14 @@ export class Client {
                 }
             }
             this.#pendingJobWaits.clear();
+            // Wait for action managers to drain
             await Promise.all(Array.from(this.#actionManagers.values()).map(async (manager) => {
                 await manager.stop();
             }));
-            await this.#telemetry.stop();
+            // Shutdown TracerProvider if configured
+            if (this.#tracerProvider) {
+                await this.#tracerProvider.shutdown();
+            }
             const dbStopped = await this.#database.stop();
             if (!dbStopped) {
                 return false;
@@ -425,6 +738,13 @@ export class Client {
         })();
         return this.#stopping;
     }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    /**
+     * Set up the shared event listener for job-status-changed events.
+     * This listener is shared across all waitForJob calls to avoid multiple listeners.
+     */
     #setupJobStatusListener() {
         if (this.#jobStatusListenerSetup) {
             return;
@@ -435,21 +755,26 @@ export class Client {
             if (!pendingWaits || pendingWaits.size === 0) {
                 return;
             }
+            // Fetch the job once for all pending waits
             const job = await this.getJobById(event.jobId);
+            // Transform to JobResult
             const result = job
                 ? {
-                    jobId: job.id,
+                    id: job.id,
                     actionName: job.actionName,
                     status: job.status,
                     groupKey: job.groupKey,
+                    description: job.description,
                     input: job.input,
                     output: job.output,
                     error: job.error,
                 }
                 : null;
+            // Resolve all pending waits for this job
             const waitsToResolve = Array.from(pendingWaits);
             this.#pendingJobWaits.delete(event.jobId);
             for (const wait of waitsToResolve) {
+                // Clean up timeout and abort signal
                 if (wait.timeoutId) {
                     clearTimeout(wait.timeoutId);
                 }
@@ -460,11 +785,18 @@ export class Client {
             }
         });
     }
+    /**
+     * Remove a specific wait request from the pending waits.
+     *
+     * @param jobId - The job ID
+     * @param resolve - The resolve function to remove
+     */
     #removeJobWait(jobId, resolve) {
         const pendingWaits = this.#pendingJobWaits.get(jobId);
         if (!pendingWaits) {
             return;
         }
+        // Find and remove the specific wait request
         for (const wait of pendingWaits) {
             if (wait.resolve === resolve) {
                 if (wait.timeoutId) {
@@ -477,10 +809,16 @@ export class Client {
                 break;
             }
         }
+        // Clean up empty sets
         if (pendingWaits.size === 0) {
             this.#pendingJobWaits.delete(jobId);
         }
     }
+    /**
+     * Execute a job by finding its action and queuing it with the appropriate ActionManager.
+     *
+     * @param job - The job to execute
+     */
     #executeJob(job) {
         if (!this.#actions) {
             return;
@@ -494,22 +832,29 @@ export class Client {
             });
             return;
         }
+        // Get or create ActionManager for this action
         let actionManager = this.#actionManagers.get(action.name);
         if (!actionManager) {
             actionManager = new ActionManager({
                 action,
                 database: this.#database,
-                telemetry: this.#telemetry,
+                tracer: this.#tracer,
                 variables: this.#variables,
                 logger: this.#logger,
                 concurrencyLimit: this.#options.actionConcurrencyLimit,
             });
             this.#actionManagers.set(action.name, actionManager);
         }
+        // Queue job execution
         actionManager.push(job).catch((err) => {
+            // Only log unexpected errors (not cancellation/timeout which are handled elsewhere)
             this.#logger.error({ err, jobId: job.id, actionName: action.name }, `[Duron] Error executing job ${job.id} for action ${action.name}`);
         });
     }
+    /**
+     * Start the pull loop for periodically fetching jobs.
+     * Only starts if not already running.
+     */
     #startPullLoop() {
         if (this.#pullInterval) {
             return;
@@ -530,8 +875,13 @@ export class Client {
                 this.#pullInterval = setTimeout(pull, this.#options.pullInterval);
             }
         };
+        // Start immediately
         pull();
     }
+    /**
+     * Setup the push listener for database notifications.
+     * Listens for 'job-available' events and fetches jobs when notified.
+     */
     #setupPushListener() {
         this.#database.on('job-available', async () => {
             this.fetch({