added nested steps and several other features (#2)

Core Features

  Nested Steps

  Steps can now create child steps with proper parent-child tracking. Child steps inherit abort signals from their parent. If a parent completes with
  unawaited children, Duron throws an UnhandledChildStepsError to prevent orphaned processes.

  Time Travel

  Jobs can be restarted from a specific step, preserving completed sibling branches. Includes time offset adjustment so preserved steps align with the current
   timeline. Supports parallel step marking so independent branches are preserved during time travel.

  Reusable Step Definitions

  New createStep() + ctx.run() API for defining modular, reusable steps. Step definitions can be composed — nested definitions can call other definitions.
  Inline steps can also call reusable definitions.

  Telemetry & Observability

  - Built-in OpenTelemetry tracing with telemetry: { local: true } (stores spans in DB) or external exporters.
  - ctx.telemetry context for recording custom metrics, creating spans, and adding attributes/events.
  - Tracer is context-aware — child spans automatically link to the current trace hierarchy.
  - Spans API endpoints for jobs and steps, with recursive descendant span querying.
  - Batch metric insertion with configurable flushDelayMs.

  Enhanced Error Handling

  - New error codes for better programmatic error detection (isTimeoutError, isCancelError).
  - ErrorMetadata interface with job ID and contextual info on errors.
  - Proper abort and settle of running steps when errors occur.

  Typed Job Results

  waitForJob and runActionAndWait now return structured JobResult / TypedJobResult with proper type safety instead of raw job objects.

  Dynamic Job Descriptions

  Actions can define a description function to generate contextual descriptions at job creation time. Jobs are filterable by description in the API and
  dashboard.

  Concurrency Step Limit

  New concurrencyStepLimit option on job creation for fine-grained control over how many steps can run concurrently within a single job.

  Dynamic Step Names

  Step names can be generated dynamically using full context (input, variables, jobId, parentStepId) via the StepNameContext interface.

  ---
  Dashboard

  - Resizable panels — drag-to-resize layout for jobs, details, and steps sections using react-resizable-panels.
  - Timeline view — integrated directly into StepList with toggle between list/timeline views.
  - Nested step visualization — color-coded nesting depth indicators.
  - Column resizing & visibility — customizable jobs table columns with pinning support.
  - Monaco JSON viewer — replaced @uiw/react-json-view with @monaco-editor/react for interactive JSON viewing.
  - Spans visualization — view OpenTelemetry spans with JSONata filtering for advanced queries.
  - Duration display — formatted durations (hh:mm:ss.mmm) on jobs and steps.
  - Theme improvements — configurable theme prop (light/dark/system) with localStorage persistence.
  - Configurable polling — PollingProvider for custom polling intervals.
  - Custom fetch — ApiProvider accepts a custom fetch function.
  - Description filtering — search/filter jobs by description.

Author: tinchoz49

.gitignore

@@ -32,3 +32,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+.claude/settings.local.json

CLAUDE.md

@@ -12,13 +12,15 @@ Duron is a modern, type-safe background job processing system built with TypeScr
 
 - **Type-Safe Actions** - Define actions with Zod schemas for input/output validation
 - **Step-Based Execution** - Break down complex workflows into manageable, retryable steps
+- **Nested Steps** - Steps can create child steps with proper parent-child tracking and abort signal propagation
 - **Intelligent Retry Logic** - Configurable exponential backoff with per-action and per-step options
 - **Flexible Sync Patterns** - Pull, push, hybrid, or manual job fetching
 - **Advanced Concurrency Control** - Per-action, per-group, and dynamic concurrency limits
 - **Multi-Process Support** - Run multiple worker processes sharing the same database
 - **Database Adapters** - PostgreSQL (production) and PGLite (development/testing)
 - **REST API Server** - Built-in Elysia-based API with advanced filtering and pagination
 - **Dashboard UI** - Beautiful React dashboard for real-time job monitoring
+- **Telemetry & Observability** - Built-in support for metrics, tracing, and custom observability with pluggable adapters
 
 ## Runtime Environment
 
@@ -85,6 +87,10 @@ The main library providing:
 - **Adapters**:
   - `duron/adapters/postgres` - PostgreSQL adapter for production
   - `duron/adapters/pglite` - PGLite adapter for development/testing
+- **Telemetry** - Configured via `telemetry` option on client:
+  - `telemetry: { local: true }` - Store spans in the database
+  - `telemetry: { traceExporter }` - Export to OpenTelemetry backends
+  - No config = telemetry disabled (default)
 
 **Key Dependencies:**
 - `zod` - Schema validation
@@ -93,6 +99,7 @@ The main library providing:
 - `pino` - Logging
 - `fastq` - Queue implementation
 - `jose` - JWT handling
+- `@opentelemetry/api` - OpenTelemetry integration (optional)
 
 ### `duron-dashboard` (React Dashboard)
 
@@ -198,6 +205,49 @@ const sendEmail = defineAction<typeof variables>()({
 })
 ```
 
+### Nested Steps
+
+Steps can create child steps using the `step()` method available in the step handler context. Child steps share abort signals with their parent and are tracked with `parentStepId` in the database.
+
+```typescript
+const processOrder = defineAction<typeof variables>()({
+  name: 'process-order',
+  input: z.object({ orderId: z.string() }),
+  output: z.object({ success: z.boolean() }),
+  handler: async (ctx) => {
+    const result = await ctx.step('process', async ({ step, signal, stepId }) => {
+      // stepId is available for the current step
+      console.log('Processing step:', stepId)
+
+      // Create child steps - they inherit the parent's abort signal
+      const validation = await step('validate', async ({ parentStepId }) => {
+        // parentStepId links back to the 'process' step
+        return { valid: true }
+      })
+
+      // Child steps can also be nested further
+      const payment = await step('charge', async ({ step: nestedStep }) => {
+        const auth = await nestedStep('authorize', async () => {
+          return { authCode: '123' }
+        })
+        return { charged: true, authCode: auth.authCode }
+      })
+
+      return { success: validation.valid && payment.charged }
+    })
+
+    return result
+  },
+})
+```
+
+**Important:** All child steps MUST be awaited before the parent step returns. If a parent step completes with unawaited children, Duron will:
+1. Abort all pending child steps
+2. Wait for them to settle
+3. Throw an `UnhandledChildStepsError`
+
+This prevents orphaned processes and ensures proper async patterns.
+
 ### Creating a Client
 
 ```typescript
@@ -228,6 +278,75 @@ const jobId = await client.runAction('send-email', {
 const job = await client.waitForJob(jobId)
 ```
 
+### Telemetry & Observability
+
+Duron provides built-in OpenTelemetry support for tracing:
+
+```typescript
+import { duron } from 'duron'
+import { postgresAdapter } from 'duron/adapters/postgres'
+
+const client = duron({
+  database: postgresAdapter({
+    connection: process.env.DATABASE_URL,
+  }),
+  // Enable local telemetry - stores spans in the database
+  telemetry: { local: true },
+  actions: { sendEmail },
+})
+```
+
+**Telemetry Configuration Options:**
+
+- `local: true | { flushDelayMs?: number }` - Store spans in the Duron database
+- `traceExporter: SpanExporter` - Export to OpenTelemetry-compatible backends (Jaeger, OTLP, etc.)
+- `spanProcessors: SpanProcessor[]` - Add custom span processors
+- `serviceName: string` - Service name for OpenTelemetry resource (default: `'duron'`)
+
+**Recording Custom Metrics:**
+
+The `telemetry` context is available in action and step handlers for recording custom metrics:
+
+```typescript
+const processAI = defineAction()({
+  name: 'process-ai',
+  handler: async (ctx) => {
+    const startTime = Date.now()
+
+    // Record job-level metrics
+    ctx.telemetry.recordMetric('ai.request.start', 1)
+    const span = ctx.telemetry.getActiveSpan()
+    span?.setAttribute('model', 'gpt-4')
+    span?.addEvent('processing.started')
+
+    const result = await ctx.step('call-api', async ({ telemetry }) => {
+      const response = await callAI(ctx.input)
+
+      // Record step-level metrics
+      telemetry.recordMetric('ai.tokens.input', response.inputTokens)
+      telemetry.recordMetric('ai.tokens.output', response.outputTokens)
+      telemetry.recordMetric('ai.latency.ms', Date.now() - startTime)
+      telemetry.getActiveSpan()?.addEvent('api.call.complete', { status: 'success' })
+
+      return response
+    })
+
+    return result
+  },
+})
+```
+
+**Accessing Metrics via API:**
+
+When using `telemetry: { local: true }`, spans are stored in the database and accessible via the REST API:
+
+```
+GET /api/jobs/:id/spans
+GET /api/steps/:id/spans
+```
+
+The dashboard also shows metrics when local telemetry is enabled.
+
 ### Creating a Server with Dashboard
 
 ```typescript
@@ -340,6 +459,8 @@ Uses Bun's bundler mode with:
 | `packages/duron/src/server.ts` | REST API server |
 | `packages/duron/src/adapters/adapter.ts` | Base adapter class |
 | `packages/duron/src/adapters/postgres/` | PostgreSQL adapter |
+| `packages/duron/src/step-manager.ts` | Step execution and nested step handling |
+| `packages/duron/src/telemetry/` | Telemetry adapters (local, opentelemetry, noop) |
 | `packages/duron-dashboard/src/DuronDashboard.tsx` | Dashboard root |
 | `packages/duron-dashboard/src/views/` | Dashboard pages |
 | `packages/examples/basic/start.ts` | Basic example |
@@ -368,15 +489,22 @@ Uses Bun's bundler mode with:
 ## Error Handling
 
 - Use `NonRetriableError` for errors that should not be retried
+- Use `UnhandledChildStepsError` is thrown when parent steps complete with unawaited children
 - Steps have built-in retry logic with exponential backoff
 - Jobs have timeout/expiration settings
 
 ```typescript
-import { NonRetriableError } from 'duron'
+import { NonRetriableError, UnhandledChildStepsError } from 'duron'
 
+// For errors that should not be retried
 if (!apiKey) {
   throw new NonRetriableError('API key is required')
 }
+
+// UnhandledChildStepsError is thrown automatically when:
+// - A parent step returns before all child steps are awaited
+// - The parent step's callback completes but children are still pending
+// This error is non-retriable and will fail the entire job
 ```
 
 ## Environment Variables
@@ -395,3 +523,5 @@ if (!apiKey) {
 4. Follow existing code patterns
 5. Use TypeScript strict mode
 6. Document public APIs with JSDoc
+
+Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.