@duckflux/core 0.6.8 → 0.7.1

package/dist/index.js

@@ -26165,8 +26165,552 @@ var require_dist2 = __commonJS((exports, module) => {
   exports.default = formatsPlugin;
 });
 
+// src/parser/schema/duckflux.schema.json
+var duckflux_schema_default;
+var init_duckflux_schema = __esm(() => {
+  duckflux_schema_default = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://raw.githubusercontent.com/duckflux/spec/main/duckflux.schema.json",
+    title: "duckflux Workflow",
+    description: "Schema for duckflux — a minimal, deterministic, runtime-agnostic workflow DSL.",
+    type: "object",
+    required: ["flow"],
+    additionalProperties: false,
+    properties: {
+      id: {
+        type: "string",
+        description: "Unique identifier for the workflow."
+      },
+      name: {
+        type: "string",
+        description: "Human-readable workflow name."
+      },
+      version: {
+        description: "Version identifier for the workflow definition.",
+        oneOf: [
+          { type: "string" },
+          { type: "integer" }
+        ]
+      },
+      defaults: {
+        $ref: "#/$defs/defaults"
+      },
+      inputs: {
+        $ref: "#/$defs/inputs"
+      },
+      participants: {
+        type: "object",
+        description: "Named steps that can be referenced in the flow.",
+        additionalProperties: {
+          $ref: "#/$defs/participant"
+        },
+        not: {
+          anyOf: [
+            { required: ["workflow"] },
+            { required: ["execution"] },
+            { required: ["input"] },
+            { required: ["output"] },
+            { required: ["env"] },
+            { required: ["loop"] },
+            { required: ["event"] }
+          ]
+        }
+      },
+      flow: {
+        $ref: "#/$defs/flowSequence"
+      },
+      output: {
+        $ref: "#/$defs/workflowOutput"
+      }
+    },
+    $defs: {
+      duration: {
+        type: "string",
+        pattern: "^[0-9]+(ms|s|m|h|d)$",
+        description: "Duration string, e.g. '30s', '5m', '2h', '1d'."
+      },
+      celExpression: {
+        type: "string",
+        description: "A Google CEL expression."
+      },
+      defaults: {
+        type: "object",
+        description: "Global defaults applied to all participants.",
+        additionalProperties: false,
+        properties: {
+          timeout: {
+            $ref: "#/$defs/duration"
+          },
+          cwd: {
+            type: "string",
+            description: "Default working directory for exec participants. Supports CEL expressions."
+          }
+        }
+      },
+      inputs: {
+        type: "object",
+        description: "Workflow input parameters. Accessed in CEL as workflow.inputs.<field>. Each key is a parameter name. Value can be null (string, no schema), or a JSON Schema object for validation.",
+        additionalProperties: {
+          oneOf: [
+            { type: "null" },
+            { $ref: "#/$defs/inputField" }
+          ]
+        }
+      },
+      inputField: {
+        type: "object",
+        description: "JSON Schema field definition with optional 'required: true' shortcut.",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["string", "integer", "number", "boolean", "array", "object"]
+          },
+          description: { type: "string" },
+          default: {},
+          required: { type: "boolean" },
+          format: { type: "string" },
+          enum: { type: "array" },
+          minimum: { type: "number" },
+          maximum: { type: "number" },
+          minLength: { type: "integer" },
+          maxLength: { type: "integer" },
+          pattern: { type: "string" },
+          items: {
+            $ref: "#/$defs/inputField"
+          }
+        },
+        additionalProperties: false
+      },
+      retryConfig: {
+        type: "object",
+        description: "Retry configuration. Only applies when onError is 'retry'.",
+        additionalProperties: false,
+        required: ["max"],
+        properties: {
+          max: {
+            type: "integer",
+            minimum: 1,
+            description: "Maximum number of retry attempts."
+          },
+          backoff: {
+            $ref: "#/$defs/duration",
+            description: "Interval between attempts. Default: 0s."
+          },
+          factor: {
+            type: "number",
+            minimum: 1,
+            description: "Backoff multiplier. Default: 1 (no escalation)."
+          }
+        }
+      },
+      onError: {
+        type: "string",
+        description: "Error handling strategy: 'fail' (default), 'skip', 'retry', or a participant name for redirect.",
+        minLength: 1
+      },
+      onTimeout: {
+        type: "string",
+        description: "Timeout handling strategy: 'fail' (default), 'skip', or a participant name for redirect.",
+        minLength: 1
+      },
+      participantInput: {
+        description: "Explicit input mapping. String for direct passthrough, object for structured mapping. Values are CEL expressions. Merged with implicit I/O chain input at runtime.",
+        oneOf: [
+          { type: "string" },
+          {
+            type: "object",
+            additionalProperties: {
+              type: "string"
+            }
+          }
+        ]
+      },
+      participantOutputSchema: {
+        type: "object",
+        description: "Output schema (JSON Schema fields). Opt-in validation.",
+        additionalProperties: {
+          $ref: "#/$defs/inputField"
+        }
+      },
+      payload: {
+        description: "Event payload. String (CEL expression) or object with CEL expressions as values.",
+        oneOf: [
+          { type: "string" },
+          {
+            type: "object",
+            additionalProperties: {}
+          }
+        ]
+      },
+      participant: {
+        type: "object",
+        required: ["type"],
+        description: "A named, reusable building block of the workflow.",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["exec", "http", "mcp", "workflow", "emit"],
+            description: "Participant type."
+          },
+          as: {
+            type: "string",
+            description: "Human-readable display name."
+          },
+          timeout: {
+            $ref: "#/$defs/duration"
+          },
+          onError: {
+            $ref: "#/$defs/onError"
+          },
+          retry: {
+            $ref: "#/$defs/retryConfig"
+          },
+          input: {
+            $ref: "#/$defs/participantInput"
+          },
+          output: {
+            $ref: "#/$defs/participantOutputSchema"
+          },
+          run: {
+            type: "string",
+            description: "[exec] Shell command to execute."
+          },
+          cwd: {
+            type: "string",
+            description: "[exec] Working directory. Supports CEL expressions."
+          },
+          url: {
+            type: "string",
+            description: "[http] Target URL. Supports CEL expressions."
+          },
+          method: {
+            type: "string",
+            enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+            description: "[http] HTTP method."
+          },
+          headers: {
+            type: "object",
+            additionalProperties: { type: "string" },
+            description: "[http] HTTP headers. Values support CEL expressions."
+          },
+          body: {
+            description: "[http] Request body. String or object. Supports CEL expressions.",
+            oneOf: [
+              { type: "string" },
+              { type: "object" }
+            ]
+          },
+          path: {
+            type: "string",
+            description: "[workflow] Path to the sub-workflow YAML file."
+          },
+          server: {
+            type: "string",
+            description: "[mcp] MCP server identifier."
+          },
+          tool: {
+            type: "string",
+            description: "[mcp] MCP tool name to invoke."
+          },
+          event: {
+            type: "string",
+            description: "[emit] Event name to emit."
+          },
+          payload: {
+            $ref: "#/$defs/payload",
+            description: "[emit] Event payload. CEL expression or object with CEL expressions."
+          },
+          ack: {
+            type: "boolean",
+            description: "[emit] If true, wait for delivery acknowledgment. Default: false.",
+            default: false
+          }
+        },
+        additionalProperties: false
+      },
+      inlineParticipant: {
+        type: "object",
+        required: ["type"],
+        description: "An inline participant definition in the flow. 'as' is optional — if omitted, the participant is anonymous and its output is only accessible via the implicit I/O chain.",
+        properties: {
+          as: {
+            type: "string",
+            description: "Optional name for inline participants. If provided, must be unique across all participant names. Enables output reference by name."
+          },
+          type: {
+            type: "string",
+            enum: ["exec", "http", "mcp", "workflow", "emit"],
+            description: "Participant type."
+          },
+          when: {
+            $ref: "#/$defs/celExpression",
+            description: "Guard condition. If false, step is skipped."
+          },
+          timeout: {
+            $ref: "#/$defs/duration"
+          },
+          onError: {
+            $ref: "#/$defs/onError"
+          },
+          retry: {
+            $ref: "#/$defs/retryConfig"
+          },
+          input: {
+            $ref: "#/$defs/participantInput"
+          },
+          output: {
+            $ref: "#/$defs/participantOutputSchema"
+          },
+          run: { type: "string" },
+          cwd: { type: "string" },
+          url: { type: "string" },
+          method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+          headers: { type: "object", additionalProperties: { type: "string" } },
+          body: { oneOf: [{ type: "string" }, { type: "object" }] },
+          path: { type: "string" },
+          server: { type: "string" },
+          tool: { type: "string" },
+          event: { type: "string" },
+          payload: { $ref: "#/$defs/payload" },
+          ack: { type: "boolean" }
+        },
+        additionalProperties: false
+      },
+      flowSequence: {
+        type: "array",
+        description: "Ordered list of flow steps. Each step's output is implicitly chained as input to the next step.",
+        minItems: 1,
+        items: {
+          $ref: "#/$defs/flowStep"
+        }
+      },
+      flowStep: {
+        description: "A single step in the flow: participant reference (string), control construct, inline participant (named or anonymous), or participant override.",
+        oneOf: [
+          {
+            type: "string",
+            description: "Simple participant reference by name."
+          },
+          { $ref: "#/$defs/loopStep" },
+          { $ref: "#/$defs/parallelStep" },
+          { $ref: "#/$defs/ifStep" },
+          { $ref: "#/$defs/setStep" },
+          { $ref: "#/$defs/waitStep" },
+          { $ref: "#/$defs/inlineParticipant" },
+          { $ref: "#/$defs/participantOverrideStep" }
+        ]
+      },
+      loopStep: {
+        type: "object",
+        required: ["loop"],
+        additionalProperties: false,
+        properties: {
+          loop: {
+            type: "object",
+            additionalProperties: false,
+            required: ["steps"],
+            properties: {
+              as: {
+                type: "string",
+                description: "Renames the loop context variable. Access as <as>.index, <as>.iteration, etc. instead of loop.*"
+              },
+              until: {
+                $ref: "#/$defs/celExpression",
+                description: "CEL condition to break out of the loop."
+              },
+              max: {
+                description: "Maximum iterations. Integer or CEL expression.",
+                oneOf: [
+                  { type: "integer", minimum: 1 },
+                  { type: "string" }
+                ]
+              },
+              steps: {
+                $ref: "#/$defs/flowSequence"
+              }
+            },
+            anyOf: [
+              { required: ["until"] },
+              { required: ["max"] }
+            ]
+          }
+        }
+      },
+      parallelStep: {
+        type: "object",
+        required: ["parallel"],
+        additionalProperties: false,
+        properties: {
+          parallel: {
+            $ref: "#/$defs/flowSequence",
+            description: "Steps to run concurrently. The chained output after a parallel block is an array of all branch outputs in declaration order."
+          }
+        }
+      },
+      ifStep: {
+        type: "object",
+        required: ["if"],
+        additionalProperties: false,
+        properties: {
+          if: {
+            type: "object",
+            required: ["condition", "then"],
+            additionalProperties: false,
+            properties: {
+              condition: {
+                $ref: "#/$defs/celExpression",
+                description: "CEL expression that determines which branch to take."
+              },
+              then: {
+                $ref: "#/$defs/flowSequence"
+              },
+              else: {
+                $ref: "#/$defs/flowSequence"
+              }
+            }
+          }
+        }
+      },
+      setStep: {
+        type: "object",
+        required: ["set"],
+        additionalProperties: false,
+        properties: {
+          set: {
+            type: "object",
+            description: "Writes values into execution.context. Each key becomes execution.context.<key>. Values are CEL expressions.",
+            minProperties: 1,
+            additionalProperties: {
+              $ref: "#/$defs/celExpression"
+            },
+            not: {
+              anyOf: [
+                { required: ["workflow"] },
+                { required: ["execution"] },
+                { required: ["input"] },
+                { required: ["output"] },
+                { required: ["env"] },
+                { required: ["loop"] },
+                { required: ["event"] }
+              ]
+            }
+          }
+        }
+      },
+      waitStep: {
+        type: "object",
+        required: ["wait"],
+        additionalProperties: false,
+        properties: {
+          wait: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              event: {
+                type: "string",
+                description: "Event name to wait for (event mode)."
+              },
+              match: {
+                $ref: "#/$defs/celExpression",
+                description: "CEL condition to match against event payload. 'event' variable contains the payload."
+              },
+              until: {
+                $ref: "#/$defs/celExpression",
+                description: "CEL condition to wait for (polling mode)."
+              },
+              poll: {
+                $ref: "#/$defs/duration",
+                description: "Polling interval for 'until' condition. Default: runtime decides."
+              },
+              timeout: {
+                $ref: "#/$defs/duration",
+                description: "Maximum wait time."
+              },
+              onTimeout: {
+                $ref: "#/$defs/onTimeout",
+                description: "Strategy when timeout is reached: 'fail' (default), 'skip', or participant name."
+              }
+            }
+          }
+        }
+      },
+      participantOverrideStep: {
+        type: "object",
+        description: "A participant reference with flow-level overrides (timeout, onError, when, input, workflow, etc.).",
+        minProperties: 1,
+        maxProperties: 1,
+        not: {
+          anyOf: [
+            { required: ["loop"] },
+            { required: ["parallel"] },
+            { required: ["if"] },
+            { required: ["wait"] },
+            { required: ["set"] },
+            { required: ["type"] }
+          ]
+        },
+        additionalProperties: {
+          type: "object",
+          properties: {
+            when: {
+              $ref: "#/$defs/celExpression",
+              description: "Guard condition. If false, step is skipped."
+            },
+            timeout: {
+              $ref: "#/$defs/duration"
+            },
+            onError: {
+              $ref: "#/$defs/onError"
+            },
+            retry: {
+              $ref: "#/$defs/retryConfig"
+            },
+            input: {
+              $ref: "#/$defs/participantInput"
+            },
+            workflow: {
+              type: "string",
+              description: "Inline sub-workflow path (alternative to defining as participant)."
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      workflowOutput: {
+        description: "Workflow output. Accessed in CEL as workflow.output. String (single CEL expression), object (structured mapping), or object with schema+map.",
+        oneOf: [
+          {
+            type: "string",
+            description: "Single CEL expression mapping."
+          },
+          {
+            type: "object",
+            description: "Structured output mapping (key → CEL expression) or schema+map.",
+            properties: {
+              schema: {
+                type: "object",
+                additionalProperties: {
+                  $ref: "#/$defs/inputField"
+                }
+              },
+              map: {
+                type: "object",
+                additionalProperties: {
+                  type: "string"
+                }
+              }
+            },
+            additionalProperties: {
+              type: "string"
+            }
+          }
+        ]
+      }
+    }
+  };
+});
+
 // src/parser/schema.ts
-import { readFileSync } from "node:fs";
 function validateSchema(workflow) {
   const valid = validate(workflow);
   if (valid) {
@@ -26178,12 +26722,12 @@ function validateSchema(workflow) {
   }));
   return { valid: false, errors };
 }
-var import__2020, import_ajv_formats, rawSchema, schema, ajv, validate;
+var import__2020, import_ajv_formats, schema, ajv, validate;
 var init_schema = __esm(() => {
+  init_duckflux_schema();
   import__2020 = __toESM(require_2020(), 1);
   import_ajv_formats = __toESM(require_dist2(), 1);
-  rawSchema = readFileSync(new URL("./schema/duckflux.schema.json", import.meta.url), "utf-8");
-  schema = JSON.parse(rawSchema);
+  schema = { ...duckflux_schema_default };
   delete schema.$schema;
   ajv = new import__2020.default({ allErrors: true, strict: false });
   import_ajv_formats.default(ajv);
@@ -26590,6 +27134,248 @@ var init_validate = __esm(() => {
   BUILTIN_ONERROR = new Set(["fail", "skip", "retry"]);
 });
 
+// src/tracer/writers/json.ts
+var exports_json = {};
+__export(exports_json, {
+  JsonTraceWriter: () => JsonTraceWriter
+});
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+class JsonTraceWriter {
+  dir;
+  filePath = "";
+  trace = {
+    execution: {
+      id: "",
+      startedAt: "",
+      finishedAt: "",
+      duration: 0,
+      status: "running",
+      inputs: null,
+      output: null
+    },
+    steps: []
+  };
+  constructor(dir) {
+    this.dir = dir;
+  }
+  async open(meta) {
+    this.filePath = join(this.dir, `${meta.id}.json`);
+    this.trace = {
+      execution: {
+        id: meta.id,
+        workflowId: meta.workflowId,
+        workflowName: meta.workflowName,
+        workflowVersion: meta.workflowVersion,
+        startedAt: meta.startedAt,
+        finishedAt: "",
+        duration: 0,
+        status: "running",
+        inputs: meta.inputs,
+        output: null
+      },
+      steps: []
+    };
+    await this.flush();
+  }
+  writeStep(step) {
+    this.trace.steps.push(step);
+    this.flushSync();
+  }
+  async finalize(meta) {
+    this.trace.execution.status = meta.status;
+    this.trace.execution.output = meta.output;
+    this.trace.execution.finishedAt = meta.finishedAt;
+    this.trace.execution.duration = meta.duration;
+    await this.flush();
+  }
+  flushSync() {
+    this.flush().catch(() => {});
+  }
+  async flush() {
+    if (!this.filePath)
+      return;
+    await writeFile(this.filePath, JSON.stringify(this.trace, null, 2), "utf-8");
+  }
+}
+var init_json = () => {};
+
+// src/tracer/writers/txt.ts
+var exports_txt = {};
+__export(exports_txt, {
+  TxtTraceWriter: () => TxtTraceWriter
+});
+import { appendFile, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+function serializeValue(value) {
+  if (value === undefined || value === null)
+    return "none";
+  if (typeof value === "string")
+    return value;
+  return JSON.stringify(value, null, 2);
+}
+function formatStep(step) {
+  const lines = [
+    `## [${step.seq}] ${step.name} (${step.type})`,
+    `startedAt: ${step.startedAt}`
+  ];
+  if (step.finishedAt)
+    lines.push(`finishedAt: ${step.finishedAt}`);
+  if (step.duration !== undefined)
+    lines.push(`duration: ${step.duration}ms`);
+  lines.push(`status: ${step.status}`);
+  if (step.loopIndex !== undefined)
+    lines.push(`loopIndex: ${step.loopIndex}`);
+  if (step.retries !== undefined && step.retries > 0)
+    lines.push(`retries: ${step.retries}`);
+  lines.push(`input: ${serializeValue(step.input)}`);
+  lines.push(`output: ${serializeValue(step.output)}`);
+  if (step.error)
+    lines.push(`error: ${step.error}`);
+  lines.push("");
+  return lines.join(`
+`);
+}
+
+class TxtTraceWriter {
+  dir;
+  filePath = "";
+  constructor(dir) {
+    this.dir = dir;
+  }
+  async open(meta) {
+    this.filePath = join2(this.dir, `${meta.id}.txt`);
+    const versionStr = meta.workflowVersion !== undefined ? ` (v${meta.workflowVersion})` : "";
+    const workflowLabel = meta.workflowName ?? meta.workflowId ?? "unnamed";
+    const header = [
+      "# execution",
+      `id: ${meta.id}`,
+      `workflow: ${workflowLabel}${versionStr}`,
+      `startedAt: ${meta.startedAt}`,
+      "status: running",
+      "",
+      "# inputs",
+      serializeValue(meta.inputs),
+      "",
+      "# steps",
+      ""
+    ].join(`
+`);
+    await writeFile2(this.filePath, header, "utf-8");
+  }
+  async writeStep(step) {
+    if (!this.filePath)
+      return;
+    await appendFile(this.filePath, formatStep(step), "utf-8");
+  }
+  async finalize(meta) {
+    if (!this.filePath)
+      return;
+    const outputSection = [
+      "# output",
+      serializeValue(meta.output),
+      ""
+    ].join(`
+`);
+    await appendFile(this.filePath, outputSection, "utf-8");
+    const content = await readFile2(this.filePath, "utf-8");
+    const updated = content.replace(/^status: running$/m, `status: ${meta.status}
+finishedAt: ${meta.finishedAt}
+duration: ${meta.duration}ms`);
+    await writeFile2(this.filePath, updated, "utf-8");
+  }
+}
+var init_txt = () => {};
+
+// src/tracer/writers/sqlite.ts
+var exports_sqlite = {};
+__export(exports_sqlite, {
+  SqliteTraceWriter: () => SqliteTraceWriter
+});
+import { join as join3 } from "node:path";
+function toJson(value) {
+  if (value === undefined || value === null)
+    return null;
+  if (typeof value === "string")
+    return value;
+  return JSON.stringify(value);
+}
+
+class SqliteTraceWriter {
+  dir;
+  db = null;
+  executionId = "";
+  constructor(dir) {
+    this.dir = dir;
+  }
+  async open(meta) {
+    this.executionId = meta.id;
+    const filePath = join3(this.dir, `${meta.id}.sqlite`);
+    const { Database } = await import("bun:sqlite");
+    this.db = new Database(filePath);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS executions (
+        id TEXT PRIMARY KEY,
+        workflow_id TEXT,
+        workflow_name TEXT,
+        workflow_version TEXT,
+        started_at TEXT NOT NULL,
+        finished_at TEXT,
+        duration_ms INTEGER,
+        status TEXT NOT NULL,
+        inputs TEXT,
+        output TEXT
+      );
+
+      CREATE TABLE IF NOT EXISTS steps (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        execution_id TEXT NOT NULL REFERENCES executions(id),
+        seq INTEGER NOT NULL,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL,
+        started_at TEXT,
+        finished_at TEXT,
+        duration_ms INTEGER,
+        status TEXT NOT NULL,
+        input TEXT,
+        output TEXT,
+        error TEXT,
+        retries INTEGER,
+        loop_index INTEGER
+      );
+    `);
+    const insert = this.db.prepare(`
+      INSERT INTO executions (id, workflow_id, workflow_name, workflow_version, started_at, status, inputs)
+      VALUES (?, ?, ?, ?, ?, 'running', ?)
+    `);
+    insert.run(meta.id, meta.workflowId ?? null, meta.workflowName ?? null, meta.workflowVersion !== undefined ? String(meta.workflowVersion) : null, meta.startedAt, toJson(meta.inputs));
+  }
+  writeStep(step) {
+    if (!this.db)
+      return;
+    const insert = this.db.prepare(`
+      INSERT INTO steps
+        (execution_id, seq, name, type, started_at, finished_at, duration_ms, status, input, output, error, retries, loop_index)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    insert.run(this.executionId, step.seq, step.name, step.type, step.startedAt ?? null, step.finishedAt ?? null, step.duration ?? null, step.status, toJson(step.input), toJson(step.output), step.error ?? null, step.retries ?? null, step.loopIndex ?? null);
+  }
+  async finalize(meta) {
+    if (!this.db)
+      return;
+    const update = this.db.prepare(`
+      UPDATE executions
+      SET status = ?, output = ?, finished_at = ?, duration_ms = ?
+      WHERE id = ?
+    `);
+    update.run(meta.status, toJson(meta.output), meta.finishedAt, Math.round(meta.duration), this.executionId);
+    this.db.close();
+    this.db = null;
+  }
+}
+var init_sqlite = () => {};
+
 // src/engine/errors.ts
 function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
@@ -27189,6 +27975,10 @@ async function executeStep(workflow, state, step, basePath = process.cwd(), engi
           output: "",
           duration: 0
         });
+        const loopIndex2 = state.isInsideLoop() ? state.currentLoopIndex() : undefined;
+        const skippedSeq = state.tracer?.startStep(stepName, participant.type, undefined, loopIndex2);
+        if (skippedSeq !== undefined)
+          state.tracer?.endStep(skippedSeq, "skipped");
       }
       return chain;
     }
@@ -27197,6 +27987,8 @@ async function executeStep(workflow, state, step, basePath = process.cwd(), engi
   const overrideInput = override?.input !== undefined ? resolveParticipantInput(override.input, state) : undefined;
   const mergedWithBase = mergeChainedInput(chain, baseInput);
   const mergedInput = mergeChainedInput(mergedWithBase, overrideInput);
+  const loopIndex = state.isInsideLoop() ? state.currentLoopIndex() : undefined;
+  const traceSeq = state.tracer?.startStep(stepName ?? "<anonymous>", participant.type, mergedInput, loopIndex);
   state.currentInput = mergedInput;
   const strategy = resolveErrorStrategy(override ?? null, participant, workflow.defaults ?? null);
   const timeoutMs = resolveTimeout(override ?? null, participant, workflow.defaults ?? null);
@@ -27274,6 +28066,8 @@ async function executeStep(workflow, state, step, basePath = process.cwd(), engi
     }
     const outputValue = result.parsedOutput ?? result.output;
     state.currentOutput = outputValue;
+    if (traceSeq !== undefined)
+      state.tracer?.endStep(traceSeq, result.status, outputValue, undefined, retries);
     return outputValue;
   } catch (error) {
     const message = String(error?.message ?? error);
@@ -27299,6 +28093,8 @@ async function executeStep(workflow, state, step, basePath = process.cwd(), engi
       if (stepName) {
         state.setResult(stepName, skipResult);
       }
+      if (traceSeq !== undefined)
+        state.tracer?.endStep(traceSeq, "skipped", undefined, message);
       return chain;
     }
     if (strategy !== "fail" && strategy !== "retry") {
@@ -27317,6 +28113,8 @@ async function executeStep(workflow, state, step, basePath = process.cwd(), engi
           ...httpMeta
         });
       }
+      if (traceSeq !== undefined)
+        state.tracer?.endStep(traceSeq, "failure", undefined, message);
       const fallbackResult = await executeStep(workflow, state, fallbackName, basePath, engineExecutor, [...fallbackStack, stepName ?? "<anonymous>"], chain, hub);
       return fallbackResult;
     }
@@ -27331,6 +28129,8 @@ async function executeStep(workflow, state, step, basePath = process.cwd(), engi
         ...httpMeta
       });
     }
+    if (traceSeq !== undefined)
+      state.tracer?.endStep(traceSeq, "failure", undefined, message);
     throw error;
   }
 }
@@ -27443,21 +28243,38 @@ async function executeControlStep(workflow, state, step, basePath = process.cwd(
   }
   const obj = step;
   if ("wait" in obj && Object.keys(obj).length === 1) {
-    const { executeWait: executeWait2 } = await Promise.resolve().then(() => (init_wait(), exports_wait));
-    return executeWait2(state, obj.wait, chain, hub, signal);
+    const loopIndex = state.isInsideLoop() ? state.currentLoopIndex() : undefined;
+    const traceSeq = state.tracer?.startStep("wait", "wait", undefined, loopIndex);
+    try {
+      const { executeWait: executeWait2 } = await Promise.resolve().then(() => (init_wait(), exports_wait));
+      const result = await executeWait2(state, obj.wait, chain, hub, signal);
+      if (traceSeq !== undefined)
+        state.tracer?.endStep(traceSeq, "success", result);
+      return result;
+    } catch (err) {
+      if (traceSeq !== undefined)
+        state.tracer?.endStep(traceSeq, "failure", undefined, String(err?.message ?? err));
+      throw err;
+    }
   }
   if ("set" in obj && Object.keys(obj).length === 1) {
     const setDef = obj.set;
     const ctx = state.toCelContext();
+    const loopIndex = state.isInsideLoop() ? state.currentLoopIndex() : undefined;
+    const traceSeq = state.tracer?.startStep("set", "set", setDef, loopIndex);
     if (!state.executionMeta.context) {
       state.executionMeta.context = {};
     }
     for (const [key, expr] of Object.entries(setDef)) {
       if (RESERVED_SET_KEYS.has(key)) {
+        if (traceSeq !== undefined)
+          state.tracer?.endStep(traceSeq, "failure", undefined, `set key '${key}' uses a reserved name`);
         throw new Error(`set key '${key}' uses a reserved name`);
       }
       state.executionMeta.context[key] = evaluateCel(expr, ctx);
     }
+    if (traceSeq !== undefined)
+      state.tracer?.endStep(traceSeq, "success", state.executionMeta.context);
     return chain;
   }
   if ("loop" in obj && Object.keys(obj).length === 1) {
@@ -27474,6 +28291,8 @@ async function executeControlStep(workflow, state, step, basePath = process.cwd(
       maxIterations = loopDef.max ?? Number.POSITIVE_INFINITY;
     }
     const hasMax = loopDef.max !== undefined;
+    const outerLoopIndex = state.isInsideLoop() ? state.currentLoopIndex() : undefined;
+    const loopTraceSeq = state.tracer?.startStep(loopAs ?? "loop", "loop", undefined, outerLoopIndex);
     state.pushLoop(loopAs);
     let loopChain = chain;
     try {
@@ -27497,6 +28316,12 @@ async function executeControlStep(workflow, state, step, basePath = process.cwd(
         iterations += 1;
         state.incrementLoop();
       }
+      if (loopTraceSeq !== undefined)
+        state.tracer?.endStep(loopTraceSeq, "success", loopChain);
+    } catch (err) {
+      if (loopTraceSeq !== undefined)
+        state.tracer?.endStep(loopTraceSeq, "failure", undefined, String(err?.message ?? err));
+      throw err;
     } finally {
       state.popLoop();
     }
@@ -27505,29 +28330,54 @@ async function executeControlStep(workflow, state, step, basePath = process.cwd(
   if ("parallel" in obj && Object.keys(obj).length === 1) {
     const parallelSteps = obj.parallel;
     const controller = new AbortController;
+    const loopIndex = state.isInsideLoop() ? state.currentLoopIndex() : undefined;
+    const parallelTraceSeq = state.tracer?.startStep("parallel", "parallel", undefined, loopIndex);
     const branchSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
-    const results = await Promise.all(parallelSteps.map(async (parallelStep) => {
-      try {
-        return await executeControlStep(workflow, state, parallelStep, basePath, engineExecutor, chain, hub, branchSignal);
-      } catch (error) {
-        controller.abort();
-        throw error;
-      }
-    }));
-    return results;
+    try {
+      const results = await Promise.all(parallelSteps.map(async (parallelStep) => {
+        try {
+          return await executeControlStep(workflow, state, parallelStep, basePath, engineExecutor, chain, hub, branchSignal);
+        } catch (error) {
+          controller.abort();
+          throw error;
+        }
+      }));
+      if (parallelTraceSeq !== undefined)
+        state.tracer?.endStep(parallelTraceSeq, "success", results);
+      return results;
+    } catch (err) {
+      if (parallelTraceSeq !== undefined)
+        state.tracer?.endStep(parallelTraceSeq, "failure", undefined, String(err?.message ?? err));
+      throw err;
+    }
   }
   if ("if" in obj && Object.keys(obj).length === 1) {
     const ifDef = obj.if;
     const condition = evaluateCel(ifDef.condition, state.toCelContext());
+    const loopIndex = state.isInsideLoop() ? state.currentLoopIndex() : undefined;
+    const ifTraceSeq = state.tracer?.startStep("if", "if", { condition: ifDef.condition }, loopIndex);
     if (typeof condition !== "boolean") {
+      if (ifTraceSeq !== undefined)
+        state.tracer?.endStep(ifTraceSeq, "failure", undefined, `if.condition must evaluate to boolean, got ${typeof condition}`);
       throw new Error(`if.condition must evaluate to boolean, got ${typeof condition}`);
     }
-    if (condition) {
-      return executeSequential(workflow, state, ifDef.then, basePath, engineExecutor, chain, hub, signal);
-    } else if (ifDef.else) {
-      return executeSequential(workflow, state, ifDef.else, basePath, engineExecutor, chain, hub, signal);
+    try {
+      let result;
+      if (condition) {
+        result = await executeSequential(workflow, state, ifDef.then, basePath, engineExecutor, chain, hub, signal);
+      } else if (ifDef.else) {
+        result = await executeSequential(workflow, state, ifDef.else, basePath, engineExecutor, chain, hub, signal);
+      } else {
+        result = chain;
+      }
+      if (ifTraceSeq !== undefined)
+        state.tracer?.endStep(ifTraceSeq, "success", result);
+      return result;
+    } catch (err) {
+      if (ifTraceSeq !== undefined)
+        state.tracer?.endStep(ifTraceSeq, "failure", undefined, String(err?.message ?? err));
+      throw err;
     }
-    return chain;
   }
   return executeStep(workflow, state, step, basePath, engineExecutor, [], chain, hub, signal);
 }
@@ -27814,6 +28664,82 @@ init_parser3();
 init_schema();
 init_validate();
 import { dirname as dirname2, resolve as resolve3 } from "node:path";
+
+// src/tracer/index.ts
+import { mkdir } from "node:fs/promises";
+
+class TraceCollector {
+  openSteps = new Map;
+  seq = 0;
+  truncateAt;
+  writer;
+  constructor(truncateAt = 1e6) {
+    this.truncateAt = truncateAt;
+  }
+  startStep(name, type3, input, loopIndex) {
+    this.seq += 1;
+    this.openSteps.set(this.seq, {
+      name,
+      type: type3,
+      startedAt: new Date().toISOString(),
+      startMs: performance.now(),
+      input: input !== undefined ? this.truncate(input) : undefined,
+      loopIndex
+    });
+    return this.seq;
+  }
+  endStep(seq, status, output, error, retries) {
+    const open = this.openSteps.get(seq);
+    if (!open)
+      return;
+    this.openSteps.delete(seq);
+    const finishedAt = new Date().toISOString();
+    const duration = Math.max(0, performance.now() - open.startMs);
+    const step = {
+      seq,
+      name: open.name,
+      type: open.type,
+      startedAt: open.startedAt,
+      finishedAt,
+      duration: Math.round(duration),
+      status,
+      ...open.input !== undefined ? { input: open.input } : {},
+      ...output !== undefined ? { output: this.truncate(output) } : {},
+      ...error !== undefined ? { error } : {},
+      ...retries !== undefined && retries > 0 ? { retries } : {},
+      ...open.loopIndex !== undefined ? { loopIndex: open.loopIndex } : {}
+    };
+    this.writer?.writeStep(step);
+  }
+  truncate(value) {
+    if (value == null)
+      return value;
+    const str = typeof value === "string" ? value : JSON.stringify(value);
+    const bytes = new TextEncoder().encode(str);
+    if (bytes.length <= this.truncateAt)
+      return value;
+    const cut = new TextDecoder().decode(bytes.slice(0, this.truncateAt));
+    return cut + "...[truncated]";
+  }
+}
+async function createTraceWriter(dir, format) {
+  await mkdir(dir, { recursive: true });
+  if (format === "json") {
+    const { JsonTraceWriter: JsonTraceWriter2 } = await Promise.resolve().then(() => (init_json(), exports_json));
+    return new JsonTraceWriter2(dir);
+  }
+  if (format === "txt") {
+    const { TxtTraceWriter: TxtTraceWriter2 } = await Promise.resolve().then(() => (init_txt(), exports_txt));
+    return new TxtTraceWriter2(dir);
+  }
+  if (format === "sqlite") {
+    const { SqliteTraceWriter: SqliteTraceWriter2 } = await Promise.resolve().then(() => (init_sqlite(), exports_sqlite));
+    return new SqliteTraceWriter2(dir);
+  }
+  throw new Error(`unknown trace format: ${format}`);
+}
+
+// src/engine/engine.ts
 init_control();
 
 // src/engine/state.ts
@@ -27831,6 +28757,7 @@ class WorkflowState {
   chainValue;
   eventPayload;
   ancestorPaths;
+  tracer;
   constructor(inputs = {}) {
     this.inputs = { ...inputs };
     this.workflowInputs = { ...inputs };
@@ -27881,6 +28808,9 @@ class WorkflowState {
     if (top)
       top.last = last2;
   }
+  isInsideLoop() {
+    return this.loopStack.length > 0;
+  }
   currentLoopContext() {
     const top = this.loopStack[this.loopStack.length - 1];
     if (!top)
@@ -27971,38 +28901,66 @@ async function executeWorkflow(workflow, inputs = {}, basePath = process.cwd(),
   if (options.cwd) {
     state.executionMeta.cwd = options.cwd;
   }
-  const startedAt = performance.now();
+  const startedAtMs = performance.now();
+  const startedAtIso = state.executionMeta.startedAt;
   if (options._ancestorPaths) {
     state.ancestorPaths = options._ancestorPaths;
   }
+  if (options.traceDir && !options._ancestorPaths) {
+    const collector = new TraceCollector;
+    const writer = await createTraceWriter(options.traceDir, options.traceFormat ?? "json");
+    collector.writer = writer;
+    state.tracer = collector;
+    await writer.open({
+      id: state.executionMeta.id,
+      workflowId: workflow.id,
+      workflowName: workflow.name,
+      workflowVersion: workflow.version,
+      startedAt: startedAtIso,
+      inputs: resolved
+    });
+  }
   const engineExecutor = async (subWorkflow, subInputs, subBasePath) => {
     return executeWorkflow(subWorkflow, subInputs, subBasePath, {
       ...options,
       _ancestorPaths: state.ancestorPaths
     });
   };
-  let chain;
-  for (const step of workflow.flow) {
-    chain = await executeControlStep(workflow, state, step, basePath, engineExecutor, chain, options.hub);
-  }
   let output;
-  if (workflow.output !== undefined) {
-    output = state.resolveOutput(workflow.output, evaluateCel);
-    if (typeof workflow.output === "object" && "schema" in workflow.output && "map" in workflow.output && typeof output === "object" && output !== null) {
-      validateOutputSchema(workflow.output.schema, output);
+  let success = false;
+  try {
+    let chain;
+    for (const step of workflow.flow) {
+      chain = await executeControlStep(workflow, state, step, basePath, engineExecutor, chain, options.hub);
+    }
+    if (workflow.output !== undefined) {
+      output = state.resolveOutput(workflow.output, evaluateCel);
+      if (typeof workflow.output === "object" && "schema" in workflow.output && "map" in workflow.output && typeof output === "object" && output !== null) {
+        validateOutputSchema(workflow.output.schema, output);
+      }
+    } else {
+      output = chain;
+    }
+    const steps = state.getAllResults();
+    success = !Object.values(steps).some((step) => step.status === "failure");
+    state.executionMeta.status = success ? "success" : "failure";
+    return {
+      success,
+      output,
+      steps,
+      duration: Math.max(0, performance.now() - startedAtMs)
+    };
+  } finally {
+    if (state.tracer?.writer) {
+      const duration = Math.max(0, performance.now() - startedAtMs);
+      await state.tracer.writer.finalize({
+        status: success ? "success" : "failure",
+        output: output ?? null,
+        finishedAt: new Date().toISOString(),
+        duration
+      }).catch(() => {});
     }
-  } else {
-    output = chain;
   }
-  const steps = state.getAllResults();
-  const success = !Object.values(steps).some((step) => step.status === "failure");
-  state.executionMeta.status = success ? "success" : "failure";
-  return {
-    success,
-    output,
-    steps,
-    duration: Math.max(0, performance.now() - startedAt)
-  };
 }
 async function runWorkflowFromFile(filePath, inputs = {}, options = {}) {
   const workflow = await parseWorkflowFile(filePath);