@theokit/sdk 1.5.0

package/dist/workflow.cjs

@@ -0,0 +1,2405 @@
+'use strict';
+
+var promises = require('fs/promises');
+var path = require('path');
+var module$1 = require('module');
+var fs = require('fs');
+var async_hooks = require('async_hooks');
+var crypto = require('crypto');
+var zod = require('zod');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn2, res) => function __init() {
+  return fn2 && (res = (0, fn2[__getOwnPropNames(fn2)[0]])(fn2 = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/errors.ts
+var TheokitAgentError, ConfigurationError, UnsupportedRunOperationError, InvalidTaskIdError, TaskNotFoundError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    TheokitAgentError = class extends Error {
+      name = "TheokitAgentError";
+      isRetryable;
+      code;
+      protoErrorCode;
+      metadata;
+      constructor(message, options = {}) {
+        super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+        this.isRetryable = options.isRetryable ?? false;
+        if (options.code !== void 0) this.code = options.code;
+        if (options.protoErrorCode !== void 0) this.protoErrorCode = options.protoErrorCode;
+        if (options.metadata !== void 0) this.metadata = options.metadata;
+      }
+    };
+    ConfigurationError = class extends TheokitAgentError {
+      name = "ConfigurationError";
+      constructor(message, options = {}) {
+        super(message, { ...options, isRetryable: false });
+      }
+    };
+    UnsupportedRunOperationError = class extends TheokitAgentError {
+      name = "UnsupportedRunOperationError";
+      operation;
+      constructor(message, operation, options = {}) {
+        super(message, {
+          ...options,
+          isRetryable: false,
+          code: options.code ?? "unsupported_run_operation"
+        });
+        this.operation = operation;
+      }
+    };
+    InvalidTaskIdError = class extends TheokitAgentError {
+      name = "InvalidTaskIdError";
+      taskId;
+      constructor(message, taskId, options = {}) {
+        super(message, {
+          ...options,
+          isRetryable: false,
+          code: "invalid_task_id"
+        });
+        this.taskId = taskId;
+      }
+    };
+    TaskNotFoundError = class extends TheokitAgentError {
+      name = "TaskNotFoundError";
+      taskId;
+      constructor(taskId, options = {}) {
+        super(`Task not found: ${taskId}`, {
+          ...options,
+          isRetryable: false,
+          code: "task_not_found"
+        });
+        this.taskId = taskId;
+      }
+    };
+  }
+});
+
+// src/types/workflow.ts
+exports.WorkflowDuplicateStepIdError = void 0; exports.WorkflowAlreadyRunningError = void 0; exports.WorkflowSnapshotNotFoundError = void 0; exports.WorkflowMaxIterationsExceededError = void 0; exports.WorkflowNotSerializableError = void 0; exports.WorkflowResumeStepNotFoundError = void 0; exports.WorkflowParallelError = void 0; exports.WorkflowCompensateNotImplementedError = void 0;
+var init_workflow = __esm({
+  "src/types/workflow.ts"() {
+    exports.WorkflowDuplicateStepIdError = class extends Error {
+      constructor(stepId) {
+        super(`Duplicate step id "${stepId}" in workflow.`);
+        this.stepId = stepId;
+      }
+      stepId;
+      name = "WorkflowDuplicateStepIdError";
+    };
+    exports.WorkflowAlreadyRunningError = class extends Error {
+      constructor(workflowName, runId) {
+        super(`Workflow "${workflowName}" run "${runId}" already in-flight.`);
+        this.workflowName = workflowName;
+        this.runId = runId;
+      }
+      workflowName;
+      runId;
+      name = "WorkflowAlreadyRunningError";
+    };
+    exports.WorkflowSnapshotNotFoundError = class extends Error {
+      constructor(runId) {
+        super(`No snapshot found for runId "${runId}". Configure persistence to enable resume.`);
+        this.runId = runId;
+      }
+      runId;
+      name = "WorkflowSnapshotNotFoundError";
+    };
+    exports.WorkflowMaxIterationsExceededError = class extends Error {
+      constructor(stepId, maxIterations) {
+        super(`Step "${stepId}" exceeded max iterations (${maxIterations}).`);
+        this.stepId = stepId;
+        this.maxIterations = maxIterations;
+      }
+      stepId;
+      maxIterations;
+      name = "WorkflowMaxIterationsExceededError";
+    };
+    exports.WorkflowNotSerializableError = class extends Error {
+      constructor(stepId, underlying) {
+        super(
+          `Workflow snapshot at step "${stepId}" failed to serialize as JSON: ${underlying.message}. Persisted snapshots support only JSON-serializable values (no BigInt, no circular refs, no class instances with cycles).`
+        );
+        this.stepId = stepId;
+        this.underlying = underlying;
+      }
+      stepId;
+      underlying;
+      name = "WorkflowNotSerializableError";
+    };
+    exports.WorkflowResumeStepNotFoundError = class extends Error {
+      constructor(stepId, workflowName) {
+        super(
+          `Cannot resume: step "${stepId}" not found in workflow "${workflowName}". The Workflow definition diverged from the snapshot.`
+        );
+        this.stepId = stepId;
+        this.workflowName = workflowName;
+      }
+      stepId;
+      workflowName;
+      name = "WorkflowResumeStepNotFoundError";
+    };
+    exports.WorkflowParallelError = class extends AggregateError {
+      constructor(errors, stepId) {
+        super(errors, `${errors.length} branch(es) failed in parallel step "${stepId}".`);
+        this.stepId = stepId;
+      }
+      stepId;
+      name = "WorkflowParallelError";
+    };
+    exports.WorkflowCompensateNotImplementedError = class extends Error {
+      constructor(stepId) {
+        super(
+          `Step "${stepId}" defines compensate, but saga engine is deferred to v1.2. Remove compensate or implement rollback manually.`
+        );
+        this.stepId = stepId;
+      }
+      stepId;
+      name = "WorkflowCompensateNotImplementedError";
+    };
+  }
+});
+async function replaceFileAtomic(filePath, content) {
+  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  const handle = await promises.open(tmp, "w");
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await promises.rename(tmp, filePath);
+  } catch (cause) {
+    await promises.unlink(tmp).catch(() => void 0);
+    throw cause;
+  }
+}
+async function atomicWriteText(filePath, content) {
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
+  await replaceFileAtomic(filePath, content);
+}
+var init_atomic_write = __esm({
+  "src/internal/persistence/atomic-write.ts"() {
+  }
+});
+function getSnapshotStoreFor(options) {
+  if (options.persistence?.backend === "json") {
+    const dir = options.persistence.dir;
+    let store = jsonStores.get(dir);
+    if (store === void 0) {
+      store = new JsonFileWorkflowSnapshotStore(dir);
+      jsonStores.set(dir, store);
+    }
+    return store;
+  }
+  return memoryStore;
+}
+function __resetSnapshotStoresForTests() {
+  jsonStores.clear();
+  memoryStore.map.clear();
+}
+var InMemoryWorkflowSnapshotStore, JsonFileWorkflowSnapshotStore, memoryStore, jsonStores;
+var init_snapshot_store = __esm({
+  "src/internal/workflow/snapshot-store.ts"() {
+    init_workflow();
+    init_atomic_write();
+    InMemoryWorkflowSnapshotStore = class {
+      map = /* @__PURE__ */ new Map();
+      async save(snapshot) {
+        try {
+          JSON.stringify(snapshot);
+        } catch (err) {
+          throw new exports.WorkflowNotSerializableError(
+            snapshot.currentStepId,
+            err instanceof Error ? err : new Error(String(err))
+          );
+        }
+        this.map.set(snapshot.runId, snapshot);
+      }
+      async load(runId) {
+        return this.map.get(runId);
+      }
+      async delete(runId) {
+        this.map.delete(runId);
+      }
+      async list(workflowName) {
+        return [...this.map.values()].filter((s) => workflowName === void 0 || s.workflowName === workflowName).map((s) => ({
+          runId: s.runId,
+          workflowName: s.workflowName,
+          suspendedAt: s.suspendedAt
+        }));
+      }
+    };
+    JsonFileWorkflowSnapshotStore = class {
+      constructor(dir) {
+        this.dir = dir;
+      }
+      dir;
+      filePath(runId) {
+        return path.join(this.dir, `${runId}.json`);
+      }
+      async save(snapshot) {
+        let serialized;
+        try {
+          serialized = JSON.stringify(snapshot);
+        } catch (err) {
+          throw new exports.WorkflowNotSerializableError(
+            snapshot.currentStepId,
+            err instanceof Error ? err : new Error(String(err))
+          );
+        }
+        await promises.mkdir(this.dir, { recursive: true });
+        await atomicWriteText(this.filePath(snapshot.runId), serialized);
+      }
+      async load(runId) {
+        try {
+          const raw = await promises.readFile(this.filePath(runId), "utf8");
+          return JSON.parse(raw);
+        } catch (err) {
+          if (err.code === "ENOENT") return void 0;
+          throw err;
+        }
+      }
+      async delete(runId) {
+        try {
+          await (await import('fs/promises')).unlink(this.filePath(runId));
+        } catch (err) {
+          if (err.code !== "ENOENT") throw err;
+        }
+      }
+      async readEntriesOrEmpty() {
+        try {
+          return await promises.readdir(this.dir);
+        } catch (err) {
+          if (err.code === "ENOENT") return [];
+          throw err;
+        }
+      }
+      async readSnapshotSafe(file) {
+        try {
+          const raw = await promises.readFile(path.join(this.dir, file), "utf8");
+          return JSON.parse(raw);
+        } catch {
+          return void 0;
+        }
+      }
+      async list(workflowName) {
+        const entries = await this.readEntriesOrEmpty();
+        const results = [];
+        for (const file of entries) {
+          if (!file.endsWith(".json")) continue;
+          const snap = await this.readSnapshotSafe(file);
+          if (snap === void 0) continue;
+          if (workflowName !== void 0 && snap.workflowName !== workflowName) continue;
+          results.push({
+            runId: snap.runId,
+            workflowName: snap.workflowName,
+            suspendedAt: snap.suspendedAt
+          });
+        }
+        return results;
+      }
+    };
+    memoryStore = new InMemoryWorkflowSnapshotStore();
+    jsonStores = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/internal/workflow/ctx.ts
+function makeStepContext(runId, signal) {
+  return {
+    runId,
+    signal,
+    log: {
+      debug: (msg, attrs) => emit("debug", runId, msg, attrs),
+      info: (msg, attrs) => emit("info", runId, msg, attrs),
+      warn: (msg, attrs) => emit("warn", runId, msg, attrs)
+    },
+    suspend: async (payload) => {
+      throw new WorkflowSuspendedSentinel(payload);
+    }
+  };
+}
+function emit(level, runId, msg, attrs) {
+  const tag = `[workflow ${runId}]`;
+  if (attrs !== void 0) {
+    if (level === "warn") console.warn(tag, msg, attrs);
+    else console.log(tag, msg, attrs);
+  } else {
+    if (level === "warn") console.warn(tag, msg);
+    else console.log(tag, msg);
+  }
+}
+function combineSignals(...signals) {
+  const valid = signals.filter((s) => s !== void 0);
+  if (valid.length === 0) return new AbortController().signal;
+  if (valid.length === 1) return valid[0];
+  const ctrl = new AbortController();
+  for (const s of valid) {
+    if (s.aborted) {
+      ctrl.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => ctrl.abort(s.reason), { once: true });
+  }
+  return ctrl.signal;
+}
+var WorkflowSuspendedSentinel;
+var init_ctx = __esm({
+  "src/internal/workflow/ctx.ts"() {
+    WorkflowSuspendedSentinel = class extends Error {
+      constructor(payload) {
+        super("__workflow_suspended__");
+        this.payload = payload;
+      }
+      payload;
+      name = "WorkflowSuspendedSentinel";
+    };
+  }
+});
+
+// src/internal/workflow/error-shape.ts
+function errToShape(err) {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message };
+  }
+  return { name: "Error", message: String(err) };
+}
+var init_error_shape = __esm({
+  "src/internal/workflow/error-shape.ts"() {
+  }
+});
+
+// src/internal/workflow/run-id.ts
+function mintRunId() {
+  return `wfr-${globalThis.crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
+}
+var init_run_id = __esm({
+  "src/internal/workflow/run-id.ts"() {
+  }
+});
+
+// src/internal/workflow/single-flight.ts
+function key(workflowId, runId) {
+  return `${workflowId}:${runId}`;
+}
+function acquireSingleFlight(workflowId, runId, workflowName) {
+  const k = key(workflowId, runId);
+  if (registry.has(k)) {
+    throw new exports.WorkflowAlreadyRunningError(workflowName, runId);
+  }
+  const controller = new AbortController();
+  registry.set(k, { controller });
+  return {
+    signal: controller.signal,
+    release: () => {
+      registry.delete(k);
+    }
+  };
+}
+var registry;
+var init_single_flight = __esm({
+  "src/internal/workflow/single-flight.ts"() {
+    init_workflow();
+    registry = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/internal/workflow/retry-policy.ts
+function backoffConfigFromPolicy(policy) {
+  return {
+    max: policy.maxAttempts,
+    init: policy.initialBackoffMs ?? 1e3,
+    coef: policy.backoffCoefficient ?? 2,
+    cap: policy.maximumBackoffMs ?? 3e4,
+    nonRetryable: new Set(policy.nonRetryableErrors ?? DEFAULT_NON_RETRYABLE)
+  };
+}
+function throwIfAborted(signal) {
+  if (signal.aborted) {
+    throw new DOMException(String(signal.reason ?? "Aborted"), "AbortError");
+  }
+}
+function shouldRethrow(err, attempt, cfg) {
+  const errName = err instanceof Error ? err.name : "Error";
+  return cfg.nonRetryable.has(errName) || attempt === cfg.max;
+}
+async function tryOnce(fn2, attempt, cfg, signal) {
+  try {
+    const value = await fn2();
+    return { value, attempts: attempt };
+  } catch (err) {
+    if (shouldRethrow(err, attempt, cfg)) throw err;
+    await abortableSleep(Math.min(cfg.init * cfg.coef ** (attempt - 1), cfg.cap), signal);
+    return { kind: "retry" };
+  }
+}
+async function withRetry(fn2, policy, signal) {
+  const cfg = backoffConfigFromPolicy(policy);
+  for (let attempt = 1; attempt <= cfg.max; attempt += 1) {
+    throwIfAborted(signal);
+    const result = await tryOnce(fn2, attempt, cfg, signal);
+    if ("value" in result) return result;
+  }
+  throw new Error("withRetry: exhausted attempts without throwing");
+}
+async function abortableSleep(ms, signal) {
+  if (signal.aborted) {
+    throw new DOMException(String(signal.reason ?? "Aborted"), "AbortError");
+  }
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve2();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      cleanup();
+      reject(new DOMException(String(signal.reason ?? "Aborted"), "AbortError"));
+    };
+    const cleanup = () => {
+      signal.removeEventListener("abort", onAbort);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var DEFAULT_NON_RETRYABLE;
+var init_retry_policy = __esm({
+  "src/internal/workflow/retry-policy.ts"() {
+    DEFAULT_NON_RETRYABLE = ["AbortError", "WorkflowSnapshotNotFoundError", "ConfigurationError"];
+  }
+});
+
+// src/internal/workflow/step-agent.ts
+async function runAgentStep(step, input, ctx) {
+  const startedAt = Date.now();
+  const agentId = step.agent.agentId;
+  if (typeof agentId === "string" && agentId.startsWith("bc-")) {
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new UnsupportedRunOperationError(
+          `Workflow agent steps not supported on CloudAgent yet (D244). agent="${agentId}", step="${step.id}"`,
+          "workflow"
+        )
+      )
+    };
+  }
+  let prompt;
+  try {
+    prompt = typeof step.promptTemplate === "string" ? step.promptTemplate : step.promptTemplate(input);
+  } catch (err) {
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(err)
+    };
+  }
+  if (typeof prompt !== "string" || prompt.length === 0) {
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new Error(`agentStep "${step.id}": rendered prompt must be a non-empty string`)
+      )
+    };
+  }
+  const exec = async () => {
+    const run = await step.agent.send(prompt);
+    const result = await run.wait();
+    if (result.status === "finished") {
+      return result.result ?? "";
+    }
+    if (result.status === "error") {
+      throw result.error ?? new Error("agent.send errored");
+    }
+    throw new Error(`Unexpected agent status: ${result.status}`);
+  };
+  try {
+    const { value, attempts } = step.retry !== void 0 ? await withRetry(exec, step.retry, ctx.signal) : { value: await exec(), attempts: 1 };
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "completed",
+      attempts,
+      durationMs: Date.now() - startedAt,
+      output: value
+    };
+  } catch (err) {
+    if (err instanceof WorkflowSuspendedSentinel) throw err;
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(err)
+    };
+  }
+}
+var init_step_agent = __esm({
+  "src/internal/workflow/step-agent.ts"() {
+    init_errors();
+    init_ctx();
+    init_error_shape();
+    init_retry_policy();
+  }
+});
+
+// src/internal/security/redact.ts
+function readEnvOnce() {
+  const raw = process.env.THEOKIT_REDACT_SECRETS;
+  if (raw === void 0) return true;
+  return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+}
+function maskToken(token) {
+  if (token.length < 18) return "***";
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+function coerceToString(value) {
+  if (typeof value === "string") return value;
+  if (value === null || value === void 0) return null;
+  if (typeof value === "object") {
+    try {
+      const s = JSON.stringify(value);
+      return s === void 0 ? null : s;
+    } catch {
+      return "[unredactable: circular]";
+    }
+  }
+  return String(value);
+}
+function redactSecrets(text, opts) {
+  const coerced = coerceToString(text);
+  if (coerced === null) return "";
+  if (!REDACT_ENABLED) return coerced;
+  let s = coerced;
+  for (const re of BUILTIN_PATTERNS) {
+    s = s.replace(re, (m) => maskToken(m));
+  }
+  for (const re of _extraPatterns) {
+    s = s.replace(re, (m) => maskToken(m));
+  }
+  {
+    s = s.replace(BEARER_PATTERN, (_, prefix) => `${prefix}***`);
+    s = s.replace(PARAM_PATTERN, (_, prefix) => `${prefix}***`);
+  }
+  return s;
+}
+var REDACT_ENABLED, warnedOptOut, BUILTIN_PATTERNS, BEARER_PATTERN, PARAM_PATTERN, _extraPatterns;
+var init_redact = __esm({
+  "src/internal/security/redact.ts"() {
+    REDACT_ENABLED = readEnvOnce();
+    warnedOptOut = false;
+    if (!REDACT_ENABLED && !warnedOptOut) {
+      process.stderr.write(
+        "[theokit-sdk] Secret redaction is DISABLED via THEOKIT_REDACT_SECRETS. Credentials may leak into errors, telemetry, logs, transcripts.\n"
+      );
+      warnedOptOut = true;
+    }
+    BUILTIN_PATTERNS = [
+      /sk-ant-[A-Za-z0-9_-]{10,}/g,
+      //   Anthropic
+      /sk-proj-[A-Za-z0-9_-]{10,}/g,
+      //  OpenAI project key (must precede sk- generic)
+      /sk-[A-Za-z0-9_-]{10,}/g,
+      //       OpenAI / OpenRouter / DeepInfra. {10,} body floor —
+      //   real keys are 40+ chars; 10-char floor still skips `sk-test` (4) and
+      //   `sk-test-key` (8). codeFile mode protects placeholders/examples.
+      /ghp_[A-Za-z0-9]{36}/g,
+      //         GitHub PAT classic (exact length)
+      /github_pat_[A-Za-z0-9_]{82}/g,
+      // GitHub PAT fine-grained
+      /glpat-[A-Za-z0-9_-]{20}/g,
+      //     GitLab PAT
+      /AKIA[A-Z0-9]{16}/g,
+      //            AWS access key
+      /AIza[A-Za-z0-9_-]{35}/g,
+      //       Google API key
+      /xox[bpasr]-[A-Za-z0-9-]{10,}/g,
+      //Slack tokens
+      /sntrys_[A-Za-z0-9]{40,}/g,
+      //     Sentry user auth
+      /sk_live_[A-Za-z0-9]{20,}/g,
+      //    Stripe secret
+      /rk_live_[A-Za-z0-9]{20,}/g
+      //    Stripe restricted
+    ];
+    BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9_\-.+/=]{8,})/g;
+    PARAM_PATTERN = /(\b(?:access_token|api_key|api-key|password|secret|x-api-key)\b["']?\s*[:=]\s*["']?)([A-Za-z0-9_\-.+/]+)/gi;
+    _extraPatterns = [];
+  }
+});
+
+// src/internal/workflow/step-branch.ts
+async function runBranchStep(step, input, ctx, options, prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  for (let i = 0; i < step.predicates.length; i += 1) {
+    const pair = step.predicates[i];
+    const [predicate, branch] = pair;
+    let matched = false;
+    try {
+      matched = await Promise.resolve(predicate(input));
+    } catch (err) {
+      const errText = err instanceof Error ? err.message : String(err);
+      console.warn(
+        redactSecrets(
+          `[workflow] branch "${step.id}" predicate ${i} threw, treating as no-match: ${errText}`
+        )
+      );
+    }
+    if (matched) {
+      const r = await runInnerSequence(branch, input, ctx, options, prevStepResults, dispatch);
+      return {
+        ...r,
+        stepId: step.id,
+        kind: "branch",
+        durationMs: Date.now() - startedAt
+      };
+    }
+  }
+  if (step.fallback !== void 0) {
+    const r = await runInnerSequence(step.fallback, input, ctx, options, prevStepResults, dispatch);
+    return {
+      ...r,
+      stepId: step.id,
+      kind: "branch",
+      durationMs: Date.now() - startedAt
+    };
+  }
+  return {
+    stepId: step.id,
+    kind: "branch",
+    status: "skipped",
+    attempts: 0,
+    durationMs: Date.now() - startedAt,
+    output: input
+  };
+}
+async function runInnerSequence(branch, input, ctx, options, prevStepResults, dispatch) {
+  let acc = input;
+  let lastAttempts = 1;
+  for (const inner of branch) {
+    const r = await dispatch(inner, acc, ctx, options, prevStepResults);
+    lastAttempts = r.attempts;
+    if (r.status === "failed") {
+      return {
+        stepId: inner.id,
+        kind: "branch",
+        status: "failed",
+        attempts: r.attempts,
+        durationMs: 0,
+        error: r.error ?? errToShape(new Error("branch inner step failed"))
+      };
+    }
+    acc = r.output;
+  }
+  return {
+    stepId: "__branch-completed__",
+    kind: "branch",
+    status: "completed",
+    attempts: lastAttempts,
+    durationMs: 0,
+    output: acc
+  };
+}
+var init_step_branch = __esm({
+  "src/internal/workflow/step-branch.ts"() {
+    init_redact();
+    init_error_shape();
+  }
+});
+
+// src/internal/workflow/step-dowhile.ts
+async function runDowhileStep(step, input, ctx, options, prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  const maxIter = step.maxIterations ?? 100;
+  let acc = input;
+  let i = 0;
+  while (true) {
+    if (i >= maxIter) {
+      return {
+        stepId: step.id,
+        kind: "dowhile",
+        status: "failed",
+        attempts: i,
+        durationMs: Date.now() - startedAt,
+        error: errToShape(new exports.WorkflowMaxIterationsExceededError(step.id, maxIter))
+      };
+    }
+    const r = await dispatch(step.step, acc, ctx, options, prevStepResults);
+    if (r.status === "failed") {
+      return {
+        stepId: step.id,
+        kind: "dowhile",
+        status: "failed",
+        attempts: i + 1,
+        durationMs: Date.now() - startedAt,
+        error: r.error
+      };
+    }
+    acc = r.output;
+    i += 1;
+    let shouldContinue = false;
+    try {
+      shouldContinue = await Promise.resolve(step.condFn(acc, i));
+    } catch (err) {
+      return {
+        stepId: step.id,
+        kind: "dowhile",
+        status: "failed",
+        attempts: i,
+        durationMs: Date.now() - startedAt,
+        error: errToShape(err)
+      };
+    }
+    if (!shouldContinue) break;
+  }
+  return {
+    stepId: step.id,
+    kind: "dowhile",
+    status: "completed",
+    attempts: i,
+    durationMs: Date.now() - startedAt,
+    output: acc
+  };
+}
+var init_step_dowhile = __esm({
+  "src/internal/workflow/step-dowhile.ts"() {
+    init_workflow();
+    init_error_shape();
+  }
+});
+
+// src/internal/workflow/step-fn.ts
+function failedFnResult(stepId, attempts, startedAt, err) {
+  return {
+    stepId,
+    kind: "fn",
+    status: "failed",
+    attempts,
+    durationMs: Date.now() - startedAt,
+    error: errToShape(err)
+  };
+}
+function validate(schema, value) {
+  if (schema === void 0) return void 0;
+  schema.parse(value);
+  return void 0;
+}
+async function execWithRetry(step, input, ctx) {
+  const exec = async () => step.fn(input, ctx);
+  if (step.retry !== void 0) return withRetry(exec, step.retry, ctx.signal);
+  return { value: await exec(), attempts: 1 };
+}
+async function runFnStep(step, input, ctx) {
+  const startedAt = Date.now();
+  if (step.compensate !== void 0) {
+    return failedFnResult(
+      step.id,
+      0,
+      startedAt,
+      new exports.WorkflowCompensateNotImplementedError(step.id)
+    );
+  }
+  try {
+    validate(step.inputSchema, input);
+  } catch (err) {
+    return failedFnResult(step.id, 0, startedAt, err);
+  }
+  try {
+    const { value, attempts } = await execWithRetry(step, input, ctx);
+    try {
+      validate(step.outputSchema, value);
+    } catch (err) {
+      return failedFnResult(step.id, attempts, startedAt, err);
+    }
+    return {
+      stepId: step.id,
+      kind: "fn",
+      status: "completed",
+      attempts,
+      durationMs: Date.now() - startedAt,
+      output: value
+    };
+  } catch (err) {
+    if (err instanceof WorkflowSuspendedSentinel) throw err;
+    return failedFnResult(step.id, 1, startedAt, err);
+  }
+}
+var init_step_fn = __esm({
+  "src/internal/workflow/step-fn.ts"() {
+    init_workflow();
+    init_ctx();
+    init_error_shape();
+    init_retry_policy();
+  }
+});
+
+// src/internal/runtime/async-semaphore.ts
+function createSemaphore(permits) {
+  if (!Number.isInteger(permits) || permits < 1) {
+    throw new ConfigurationError(
+      `async-semaphore: permits must be a positive integer, got ${permits}`,
+      { code: "invalid_concurrency" }
+    );
+  }
+  let active = 0;
+  const queue = [];
+  function tryGrant() {
+    if (active < permits && queue.length > 0) {
+      const resolve2 = queue.shift();
+      if (resolve2 !== void 0) {
+        active += 1;
+        resolve2();
+      }
+    }
+  }
+  return {
+    inFlight: () => active,
+    pending: () => queue.length + active,
+    async acquire() {
+      await new Promise((resolve2) => {
+        queue.push(resolve2);
+        tryGrant();
+      });
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        active -= 1;
+        tryGrant();
+      };
+    }
+  };
+}
+var init_async_semaphore = __esm({
+  "src/internal/runtime/async-semaphore.ts"() {
+    init_errors();
+  }
+});
+
+// src/internal/workflow/step-foreach.ts
+async function runForeachStep(step, _input, ctx, options, prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  const sourceResult = prevStepResults.find((r) => r.stepId === step.iterableFrom);
+  if (sourceResult === void 0) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new Error(
+          `foreach.iterableFrom "${step.iterableFrom}" not found in top-level steps. It must reference an earlier top-level step ID \u2014 nested step IDs inside parallel/branch/foreach blocks are not visible here.`
+        )
+      )
+    };
+  }
+  const items = sourceResult.output;
+  if (!Array.isArray(items)) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new Error(
+          `foreach.iterableFrom "${step.iterableFrom}" output must be Array, got ${typeof items}.`
+        )
+      )
+    };
+  }
+  if (items.length === 0) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "completed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      output: []
+    };
+  }
+  const concurrency = step.concurrency ?? 4;
+  const sem = createSemaphore(Math.max(1, Math.min(concurrency, items.length)));
+  const failures = [];
+  const outputs = new Array(items.length);
+  await Promise.all(
+    items.map(async (item, idx) => {
+      const release = await sem.acquire();
+      try {
+        const r = await dispatch(step.step, item, ctx, options, prevStepResults);
+        if (r.status === "failed") {
+          failures.push(new Error(`foreach item ${idx} failed: ${r.error?.message ?? "unknown"}`));
+        } else {
+          outputs[idx] = r.output;
+        }
+      } finally {
+        release();
+      }
+    })
+  );
+  if (failures.length > 0) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "failed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new AggregateError(failures, `foreach "${step.id}" had ${failures.length} failure(s)`)
+      )
+    };
+  }
+  return {
+    stepId: step.id,
+    kind: "foreach",
+    status: "completed",
+    attempts: 1,
+    durationMs: Date.now() - startedAt,
+    output: outputs
+  };
+}
+var init_step_foreach = __esm({
+  "src/internal/workflow/step-foreach.ts"() {
+    init_async_semaphore();
+    init_error_shape();
+  }
+});
+
+// src/internal/workflow/step-parallel.ts
+async function runParallelStep(step, input, ctx, options, _prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  const policy = step.errorPolicy ?? "fail-fast";
+  const branchCount = step.branches.length;
+  if (branchCount === 0) {
+    return {
+      stepId: step.id,
+      kind: "parallel",
+      status: "completed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      output: []
+    };
+  }
+  const concurrency = step.concurrency ?? branchCount;
+  const sem = createSemaphore(Math.max(1, Math.min(concurrency, branchCount)));
+  const failFastCtrl = policy === "fail-fast" ? new AbortController() : void 0;
+  const branchSignal = policy === "fail-fast" ? mergeSignals(ctx.signal, failFastCtrl.signal) : ctx.signal;
+  const semBranchPromises = step.branches.map(async (branch, branchIdx) => {
+    const release = await sem.acquire();
+    try {
+      return await runBranch(
+        branch,
+        input,
+        { ...ctx, signal: branchSignal },
+        options,
+        dispatch,
+        branchIdx
+      );
+    } finally {
+      release();
+    }
+  });
+  if (policy === "fail-fast") {
+    try {
+      const outputs2 = await Promise.all(semBranchPromises);
+      return {
+        stepId: step.id,
+        kind: "parallel",
+        status: "completed",
+        attempts: 1,
+        durationMs: Date.now() - startedAt,
+        output: outputs2
+      };
+    } catch (err) {
+      failFastCtrl?.abort(err);
+      const settled2 = await Promise.allSettled(semBranchPromises);
+      const errors = settled2.filter((s) => s.status === "rejected").map((s) => s.reason instanceof Error ? s.reason : new Error(String(s.reason)));
+      return {
+        stepId: step.id,
+        kind: "parallel",
+        status: "failed",
+        attempts: 1,
+        durationMs: Date.now() - startedAt,
+        error: errToShape(new exports.WorkflowParallelError(errors, step.id)),
+        output: void 0
+      };
+    }
+  }
+  const settled = await Promise.allSettled(semBranchPromises);
+  const outputs = settled.map(
+    (s) => s.status === "fulfilled" ? { ok: true, value: s.value } : { ok: false, error: errToShape(s.reason) }
+  );
+  return {
+    stepId: step.id,
+    kind: "parallel",
+    status: "completed",
+    attempts: 1,
+    durationMs: Date.now() - startedAt,
+    output: outputs
+  };
+}
+async function runBranch(branch, input, ctx, options, dispatch, branchIdx) {
+  let acc = input;
+  for (const inner of branch) {
+    const r = await dispatch(inner, acc, ctx, options, []);
+    if (r.status === "failed") {
+      throw new Error(
+        `parallel branch ${branchIdx} step "${inner.id}" failed: ${r.error?.message ?? "unknown"}`
+      );
+    }
+    acc = r.output;
+  }
+  return acc;
+}
+function mergeSignals(a, b) {
+  if (a.aborted) return a;
+  if (b.aborted) return b;
+  const ctrl = new AbortController();
+  const onAbortA = () => ctrl.abort(a.reason);
+  const onAbortB = () => ctrl.abort(b.reason);
+  a.addEventListener("abort", onAbortA, { once: true });
+  b.addEventListener("abort", onAbortB, { once: true });
+  return ctrl.signal;
+}
+var init_step_parallel = __esm({
+  "src/internal/workflow/step-parallel.ts"() {
+    init_workflow();
+    init_async_semaphore();
+    init_error_shape();
+  }
+});
+
+// src/internal/workflow/step-sleep.ts
+async function runSleepStep(step, input, ctx) {
+  const startedAt = Date.now();
+  try {
+    await abortableSleep(step.durationMs, ctx.signal);
+    return {
+      stepId: step.id,
+      kind: "sleep",
+      status: "completed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      output: input
+      // sleep is a pass-through
+    };
+  } catch (err) {
+    return {
+      stepId: step.id,
+      kind: "sleep",
+      status: "failed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(err)
+    };
+  }
+}
+var init_step_sleep = __esm({
+  "src/internal/workflow/step-sleep.ts"() {
+    init_error_shape();
+    init_retry_policy();
+  }
+});
+function getTracer(name, version = "1.0.0") {
+  const cached = tracerCache.get(name);
+  if (cached !== void 0) return cached.tracer ?? void 0;
+  try {
+    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('workflow.cjs', document.baseURI).href)));
+    const otel = r("@opentelemetry/api");
+    if (otel.trace?.getTracer === void 0) {
+      tracerCache.set(name, { tracer: null });
+      return void 0;
+    }
+    const tracer = otel.trace.getTracer(name, version);
+    tracerCache.set(name, { tracer });
+    return tracer;
+  } catch {
+    tracerCache.set(name, { tracer: null });
+    return void 0;
+  }
+}
+var noopSpan, tracerCache;
+var init_tracer_loader = __esm({
+  "src/internal/observability/tracer-loader.ts"() {
+    noopSpan = {
+      setAttribute: () => noopSpan,
+      end: () => void 0
+    };
+    tracerCache = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/internal/workflow/telemetry.ts
+function startWorkflowRunSpan(info) {
+  const tracer = getTracer(TRACER_NAME);
+  if (tracer === void 0) return noopSpan;
+  return tracer.startSpan("workflow.run", {
+    attributes: {
+      "workflow.name": info.workflowName,
+      "workflow.run_id": info.runId
+    }
+  });
+}
+function startWorkflowStepSpan(info) {
+  const tracer = getTracer(TRACER_NAME);
+  if (tracer === void 0) return noopSpan;
+  return tracer.startSpan(`workflow.step.${info.stepId}`, {
+    attributes: {
+      "step.id": info.stepId,
+      "step.kind": info.kind,
+      "step.attempt": info.attempt
+    }
+  });
+}
+var TRACER_NAME;
+var init_telemetry = __esm({
+  "src/internal/workflow/telemetry.ts"() {
+    init_tracer_loader();
+    TRACER_NAME = "@theokit/sdk/workflow";
+  }
+});
+
+// src/internal/workflow/executor.ts
+var executor_exports = {};
+__export(executor_exports, {
+  dispatchStep: () => dispatchStep,
+  executeWorkflow: () => executeWorkflow,
+  resumeWorkflow: () => resumeWorkflow
+});
+async function handleSuspend(err, ctx) {
+  try {
+    await saveSnapshot({
+      runId: ctx.runId,
+      workflowName: ctx.options.name,
+      currentStepId: ctx.step.id,
+      suspendedPayload: err.payload,
+      stepResults: ctx.stepResults,
+      accumulatedInput: ctx.acc,
+      options: ctx.options
+    });
+  } catch (snapErr) {
+    ctx.stepSpan.setAttribute("step.status", "failed");
+    ctx.stepSpan.end();
+    return {
+      kind: "failed",
+      run: assembleRun({
+        runId: ctx.runId,
+        name: ctx.name,
+        status: "failed",
+        stepResults: ctx.stepResults,
+        startedAt: ctx.startedAt,
+        error: errToShape(snapErr)
+      })
+    };
+  }
+  ctx.stepSpan.setAttribute("step.status", "suspended");
+  ctx.stepSpan.end();
+  return {
+    kind: "suspended",
+    run: assembleRun({
+      runId: ctx.runId,
+      name: ctx.name,
+      status: "suspended",
+      stepResults: [
+        ...ctx.stepResults,
+        {
+          stepId: ctx.step.id,
+          kind: ctx.step.kind,
+          status: "suspended",
+          attempts: 1,
+          durationMs: 0,
+          output: void 0
+        }
+      ],
+      startedAt: ctx.startedAt
+    })
+  };
+}
+async function runOneStep(args) {
+  const stepSpan = startWorkflowStepSpan({
+    stepId: args.step.id,
+    kind: args.step.kind,
+    attempt: 1
+  });
+  let result;
+  try {
+    result = await dispatchStep(args.step, args.acc, args.ctx, args.options, args.stepResults);
+  } catch (err) {
+    if (err instanceof WorkflowSuspendedSentinel) {
+      const outcome = await handleSuspend(err, { ...args, stepSpan });
+      return { kind: "terminal", run: outcome.run };
+    }
+    result = {
+      stepId: args.step.id,
+      kind: args.step.kind,
+      status: "failed",
+      attempts: 1,
+      durationMs: 0,
+      error: errToShape(err)
+    };
+  }
+  stepSpan.setAttribute("step.status", result.status);
+  stepSpan.setAttribute("step.attempts", result.attempts);
+  stepSpan.end();
+  return { kind: "ok", result };
+}
+function abortRun(name, runId, startedAt, stepResults, signal) {
+  return assembleRun({
+    runId,
+    name,
+    status: "cancelled",
+    stepResults,
+    startedAt,
+    error: { name: "AbortError", message: String(signal.reason ?? "Aborted") }
+  });
+}
+async function runStepsLoop(params) {
+  const { options, steps, ctx, runId, startedAt, signal } = params;
+  const stepResults = [];
+  let acc = params.input;
+  for (const step of steps) {
+    if (signal.aborted) return abortRun(options.name, runId, startedAt, stepResults, signal);
+    const outcome = await runOneStep({
+      step,
+      acc,
+      ctx,
+      options,
+      stepResults,
+      runId,
+      name: options.name,
+      startedAt
+    });
+    if (outcome.kind === "terminal") return outcome.run;
+    stepResults.push(outcome.result);
+    if (outcome.result.status === "failed") {
+      return assembleRun({
+        runId,
+        name: options.name,
+        status: "failed",
+        stepResults,
+        startedAt,
+        error: outcome.result.error
+      });
+    }
+    acc = outcome.result.output;
+  }
+  return assembleRun({
+    runId,
+    name: options.name,
+    status: "completed",
+    output: acc,
+    stepResults,
+    startedAt
+  });
+}
+async function executeWorkflow(options, steps, input, runOpts) {
+  const runId = runOpts?.runId ?? mintRunId();
+  const workflowId = options.workflowId ?? `wf-anon`;
+  const flight = acquireSingleFlight(workflowId, runId, options.name);
+  const startedAt = Date.now();
+  const signal = combineSignals(runOpts?.signal, flight.signal);
+  const runSpan = startWorkflowRunSpan({ workflowName: options.name, runId });
+  if (signal.aborted) {
+    flight.release();
+    runSpan.setAttribute("workflow.status", "cancelled");
+    runSpan.end();
+    return abortRun(options.name, runId, startedAt, [], signal);
+  }
+  const ctx = makeStepContext(runId, signal);
+  try {
+    return await runStepsLoop({
+      options,
+      steps,
+      input,
+      ctx,
+      runId,
+      startedAt,
+      signal
+    });
+  } finally {
+    runSpan.end();
+    flight.release();
+  }
+}
+async function dispatchStep(step, input, ctx, options, prevStepResults) {
+  switch (step.kind) {
+    case "fn":
+      return runFnStep(step, input, ctx);
+    case "agent":
+      return runAgentStep(step, input, ctx);
+    case "parallel":
+      return runParallelStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "branch":
+      return runBranchStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "foreach":
+      return runForeachStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "dowhile":
+      return runDowhileStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "sleep":
+      return runSleepStep(step, input, ctx);
+    case "suspend":
+      throw new WorkflowSuspendedSentinel(void 0);
+    default: {
+      const _exhaustive = step;
+      throw new Error(`Unknown step kind: ${_exhaustive.kind}`);
+    }
+  }
+}
+function assembleRun(params) {
+  const endedAt = Date.now();
+  return {
+    id: params.runId,
+    name: params.name,
+    status: params.status,
+    startedAt: params.startedAt,
+    endedAt,
+    stepResults: params.stepResults,
+    ...params.output !== void 0 ? { output: params.output } : {},
+    ...params.error !== void 0 ? { error: params.error } : {}
+  };
+}
+async function saveSnapshot(p) {
+  const snapshot = {
+    _schemaVersion: 1,
+    runId: p.runId,
+    workflowName: p.workflowName,
+    currentStepId: p.currentStepId,
+    suspendedPayload: p.suspendedPayload,
+    stepResults: p.stepResults,
+    accumulatedInput: p.accumulatedInput,
+    suspendedAt: Date.now()
+  };
+  const store = getSnapshotStoreFor(p.options);
+  await store.save(snapshot);
+}
+async function resumeWorkflow(opts) {
+  const wfInternal = opts.workflow;
+  const options = wfInternal.__options;
+  const steps = wfInternal.__steps;
+  if (options === void 0 || steps === void 0) {
+    throw new Error("Workflow.resume requires an instance from Workflow.create().commit()");
+  }
+  const store = getSnapshotStoreFor(options);
+  const snapshot = await store.load(opts.runId);
+  if (snapshot === void 0) {
+    throw new exports.WorkflowSnapshotNotFoundError(opts.runId);
+  }
+  const stepIdx = steps.findIndex((s) => s.id === snapshot.currentStepId);
+  if (stepIdx < 0) {
+    throw new exports.WorkflowResumeStepNotFoundError(snapshot.currentStepId, snapshot.workflowName);
+  }
+  const suspendStep = steps[stepIdx];
+  if (suspendStep !== void 0 && suspendStep.kind === "suspend" && suspendStep.payloadSchema !== void 0) {
+    suspendStep.payloadSchema.parse(opts.payload);
+  }
+  const resumeInput = opts.payload !== void 0 ? opts.payload : snapshot.accumulatedInput;
+  const remainingSteps = steps.slice(stepIdx + 1);
+  await store.delete(opts.runId);
+  return executeWorkflow(options, remainingSteps, resumeInput, {
+    signal: opts.signal,
+    runId: opts.runId
+  });
+}
+var init_executor = __esm({
+  "src/internal/workflow/executor.ts"() {
+    init_workflow();
+    init_ctx();
+    init_error_shape();
+    init_run_id();
+    init_single_flight();
+    init_snapshot_store();
+    init_step_agent();
+    init_step_branch();
+    init_step_dowhile();
+    init_step_fn();
+    init_step_foreach();
+    init_step_parallel();
+    init_step_sleep();
+    init_telemetry();
+  }
+});
+
+// src/types/task.ts
+function isValidTaskId(id, allowReserved) {
+  if (!TASK_ID_GRAMMAR.test(id)) return false;
+  if (allowReserved) return true;
+  for (const prefix of RESERVED_PREFIXES) {
+    if (id.startsWith(prefix)) return false;
+  }
+  return true;
+}
+var TASK_ID_GRAMMAR, RESERVED_PREFIXES;
+var init_task = __esm({
+  "src/types/task.ts"() {
+    TASK_ID_GRAMMAR = /^[a-z0-9][a-z0-9_-]*$/;
+    RESERVED_PREFIXES = ["wf-", "b-", "cron-"];
+  }
+});
+
+// src/internal/task/ring-buffer.ts
+var RingBuffer;
+var init_ring_buffer = __esm({
+  "src/internal/task/ring-buffer.ts"() {
+    RingBuffer = class {
+      constructor(cap) {
+        this.cap = cap;
+        if (!Number.isInteger(cap) || cap < 1) {
+          throw new Error(`RingBuffer capacity must be a positive integer, got ${cap}`);
+        }
+      }
+      cap;
+      buf = [];
+      truncated = false;
+      push(item) {
+        if (this.buf.length >= this.cap) {
+          this.buf.shift();
+          this.truncated = true;
+        }
+        this.buf.push(item);
+      }
+      drain() {
+        return { items: this.buf.slice(), truncated: this.truncated };
+      }
+      size() {
+        return this.buf.length;
+      }
+      wasTruncated() {
+        return this.truncated;
+      }
+    };
+  }
+});
+function assertValidIdForStore(id) {
+  if (!isValidTaskId(
+    id,
+    /* allowReserved */
+    true
+  )) {
+    throw new InvalidTaskIdError(`store rejects invalid task id: ${id}`, id);
+  }
+}
+function terminalTimestamp(h) {
+  if (h.state === "finished") return h.finishedAt;
+  if (h.state === "error") return h.erroredAt;
+  if (h.state === "cancelled") return h.cancelledAt;
+  return void 0;
+}
+function isTerminal(state2) {
+  return state2 === "finished" || state2 === "error" || state2 === "cancelled";
+}
+function matchesState(h, filter) {
+  if (filter.state === void 0) return true;
+  const states = Array.isArray(filter.state) ? filter.state : [filter.state];
+  return states.includes(h.state);
+}
+function matchesKind(h, filter) {
+  if (filter.kind === void 0) return true;
+  const kinds = Array.isArray(filter.kind) ? filter.kind : [filter.kind];
+  return kinds.includes(h.kind);
+}
+function matchesTime(h, filter) {
+  if (filter.submittedAfter !== void 0 && h.submittedAt <= filter.submittedAfter) return false;
+  if (filter.submittedBefore !== void 0 && h.submittedAt >= filter.submittedBefore) return false;
+  return true;
+}
+function matchesFilter(h, filter) {
+  return matchesState(h, filter) && matchesKind(h, filter) && matchesTime(h, filter);
+}
+function applyFilter(values, filter) {
+  const limit = filter.limit ?? DEFAULT_LIST_LIMIT;
+  const out = [];
+  for (const h of values) {
+    if (matchesFilter(h, filter)) {
+      out.push(h);
+      if (out.length >= limit) break;
+    }
+  }
+  return out;
+}
+function getTaskStoreFor(options) {
+  if (options.backend === "memory") return new InMemoryTaskStore();
+  return new JsonFileTaskStore(options.dir);
+}
+var JSON_LOAD_CAP, DEFAULT_LIST_LIMIT, InMemoryTaskStore, JsonFileTaskStore;
+var init_store = __esm({
+  "src/internal/task/store.ts"() {
+    init_errors();
+    init_task();
+    init_atomic_write();
+    JSON_LOAD_CAP = 256;
+    DEFAULT_LIST_LIMIT = 100;
+    InMemoryTaskStore = class {
+      map = /* @__PURE__ */ new Map();
+      async insert(handle) {
+        assertValidIdForStore(handle.id);
+        this.map.set(handle.id, handle);
+      }
+      async update(id, mutate) {
+        assertValidIdForStore(id);
+        const existing = this.map.get(id);
+        if (existing === void 0) return void 0;
+        const next = mutate(existing);
+        this.map.set(id, next);
+        return next;
+      }
+      async get(id) {
+        assertValidIdForStore(id);
+        return this.map.get(id);
+      }
+      async list(filter) {
+        return applyFilter(this.map.values(), filter);
+      }
+      async delete(id) {
+        assertValidIdForStore(id);
+        return this.map.delete(id);
+      }
+      async evictTerminalOlderThan(epochMs) {
+        let count = 0;
+        for (const [id, h] of this.map.entries()) {
+          if (!isTerminal(h.state)) continue;
+          const ts = terminalTimestamp(h);
+          if (ts !== void 0 && ts < epochMs) {
+            this.map.delete(id);
+            count++;
+          }
+        }
+        return count;
+      }
+    };
+    JsonFileTaskStore = class {
+      constructor(dir) {
+        this.dir = dir;
+        try {
+          fs.mkdirSync(dir, { recursive: true });
+        } catch (err) {
+          if (err.code !== "EEXIST") throw err;
+        }
+      }
+      dir;
+      filePath(id) {
+        return path.join(this.dir, `${id}.json`);
+      }
+      async insert(handle) {
+        assertValidIdForStore(handle.id);
+        await atomicWriteText(this.filePath(handle.id), JSON.stringify(handle));
+      }
+      async update(id, mutate) {
+        assertValidIdForStore(id);
+        const existing = await this.get(id);
+        if (existing === void 0) return void 0;
+        const next = mutate(existing);
+        await atomicWriteText(this.filePath(id), JSON.stringify(next));
+        return next;
+      }
+      async get(id) {
+        assertValidIdForStore(id);
+        try {
+          const raw = await promises.readFile(this.filePath(id), "utf8");
+          return JSON.parse(raw);
+        } catch (err) {
+          const code = err.code;
+          if (code === "ENOENT") return void 0;
+          process.stderr.write(`[task-store] failed to read ${id}: ${err.message}
+`);
+          return void 0;
+        }
+      }
+      async list(filter) {
+        let entries;
+        try {
+          entries = fs.readdirSync(this.dir);
+        } catch (err) {
+          if (err.code === "ENOENT") return [];
+          throw err;
+        }
+        const candidates = entries.filter((name) => name.endsWith(".json") && !name.includes(".tmp")).slice(0, JSON_LOAD_CAP);
+        const loaded = await Promise.all(
+          candidates.map(async (name) => {
+            const id = name.slice(0, -".json".length);
+            if (!isValidTaskId(id, true)) return void 0;
+            return this.get(id);
+          })
+        );
+        const handles = loaded.filter((h) => h !== void 0);
+        return applyFilter(handles, filter);
+      }
+      async delete(id) {
+        assertValidIdForStore(id);
+        try {
+          await promises.unlink(this.filePath(id));
+          return true;
+        } catch (err) {
+          if (err.code === "ENOENT") return false;
+          throw err;
+        }
+      }
+      async evictTerminalOlderThan(epochMs) {
+        const handles = await this.list({ state: ["finished", "error", "cancelled"], limit: 256 });
+        let count = 0;
+        for (const h of handles) {
+          const ts = terminalTimestamp(h);
+          if (ts !== void 0 && ts < epochMs) {
+            if (await this.delete(h.id)) count++;
+          }
+        }
+        return count;
+      }
+    };
+  }
+});
+
+// src/internal/task/subscribe.ts
+function isTerminalEvent(event) {
+  return event.type === "finished" || event.type === "errored" || event.type === "cancelled";
+}
+function drainBuffered(buffer) {
+  const { items, truncated } = buffer.drain();
+  const queue = items.slice();
+  if (truncated && queue.length > 0) {
+    const first = queue[0];
+    if (first !== void 0 && first.type === "submitted") {
+      queue[0] = { ...first, truncated: true };
+    }
+  }
+  return queue;
+}
+function buildSubscribe(deps) {
+  return function subscribe2(id) {
+    if (!isValidTaskId(id, true)) throw new TaskNotFoundError(id);
+    const buffer = deps.getBuffer(id);
+    if (buffer === void 0) throw new TaskNotFoundError(id);
+    return {
+      [Symbol.asyncIterator]() {
+        return new TaskIterator(buffer, id, deps);
+      }
+    };
+  };
+}
+var TaskIterator;
+var init_subscribe = __esm({
+  "src/internal/task/subscribe.ts"() {
+    init_errors();
+    init_task();
+    TaskIterator = class {
+      constructor(buffer, id, deps) {
+        this.id = id;
+        this.deps = deps;
+        this.queue = drainBuffered(buffer);
+        this.callback = (e) => this.deliver(e);
+        deps.getOrCreateSubscriberSet(id).add(this.callback);
+      }
+      id;
+      deps;
+      queue;
+      pendingResolve;
+      done = false;
+      callback;
+      deliver(e) {
+        if (this.done) return;
+        if (this.pendingResolve !== void 0) {
+          const r = this.pendingResolve;
+          this.pendingResolve = void 0;
+          r({ value: e, done: false });
+        } else {
+          this.queue.push(e);
+        }
+      }
+      cleanup() {
+        if (this.done) return;
+        this.done = true;
+        this.deps.removeSubscriber(this.id, this.callback);
+        if (this.pendingResolve !== void 0) {
+          const r = this.pendingResolve;
+          this.pendingResolve = void 0;
+          r({ value: void 0, done: true });
+        }
+      }
+      dequeue() {
+        const event = this.queue.shift();
+        if (event === void 0) return void 0;
+        if (isTerminalEvent(event)) queueMicrotask(() => this.cleanup());
+        return { value: event, done: false };
+      }
+      next() {
+        if (this.done) return Promise.resolve({ value: void 0, done: true });
+        const queued = this.dequeue();
+        if (queued !== void 0) return Promise.resolve(queued);
+        return new Promise((resolve2) => {
+          this.pendingResolve = resolve2;
+        });
+      }
+      return() {
+        this.cleanup();
+        return Promise.resolve({ value: void 0, done: true });
+      }
+    };
+  }
+});
+
+// src/internal/task/telemetry.ts
+function startTaskSubmitSpan(info) {
+  const tracer = getTracer(TRACER_NAME2);
+  if (tracer === void 0) return noopSpan;
+  return tracer.startSpan("task.submit", {
+    attributes: {
+      "task.id": info.taskId,
+      "task.kind": info.kind
+    }
+  });
+}
+function startTaskTransitionSpan(info) {
+  const tracer = getTracer(TRACER_NAME2);
+  if (tracer === void 0) return noopSpan;
+  return tracer.startSpan("task.transition", {
+    attributes: {
+      "task.id": info.taskId,
+      "task.state.from": info.from,
+      "task.state.to": info.to
+    }
+  });
+}
+function startTaskCancelSpan(info) {
+  const tracer = getTracer(TRACER_NAME2);
+  if (tracer === void 0) return noopSpan;
+  return tracer.startSpan("task.cancel", {
+    attributes: {
+      "task.id": info.taskId,
+      "task.cancel.via": info.via,
+      ...info.reason !== void 0 ? { "task.cancel.reason": info.reason } : {}
+    }
+  });
+}
+var TRACER_NAME2;
+var init_telemetry2 = __esm({
+  "src/internal/task/telemetry.ts"() {
+    init_tracer_loader();
+    TRACER_NAME2 = "@theokit/sdk/task";
+  }
+});
+
+// src/internal/task/registry.ts
+var registry_exports = {};
+__export(registry_exports, {
+  __getCancelRequestedForTests: () => __getCancelRequestedForTests,
+  __getSubscribersCountForTests: () => __getSubscribersCountForTests,
+  __resetTaskRegistryForTests: () => __resetTaskRegistryForTests,
+  cancel: () => cancel,
+  configure: () => configure,
+  evictNow: () => evictNow,
+  get: () => get,
+  list: () => list,
+  submit: () => submit,
+  subscribe: () => subscribe
+});
+function buildState(opts) {
+  const store = opts.store === void 0 ? new InMemoryTaskStore() : getTaskStoreFor(opts.store);
+  return {
+    store,
+    semaphore: createSemaphore(opts.maxConcurrent ?? DEFAULT_CONCURRENCY),
+    aborters: /* @__PURE__ */ new Map(),
+    buffers: /* @__PURE__ */ new Map(),
+    subscribers: /* @__PURE__ */ new Map(),
+    retentionMs: opts.retentionMs ?? DEFAULT_RETENTION_MS,
+    firstSubmitSeen: false
+  };
+}
+function __resetTaskRegistryForTests() {
+  if (state.evictTimer !== void 0) clearInterval(state.evictTimer);
+  state = buildState({});
+}
+function __getSubscribersCountForTests(taskId) {
+  return state.subscribers.get(taskId)?.size ?? 0;
+}
+function __getCancelRequestedForTests(_taskId) {
+  return void 0;
+}
+function configure(opts) {
+  if (state.firstSubmitSeen) {
+    process.stderr.write(
+      "[task] configure() ignored \u2014 registry already in use; reset via __resetTaskRegistryForTests()\n"
+    );
+    return;
+  }
+  if (state.evictTimer !== void 0) clearInterval(state.evictTimer);
+  state = buildState(opts);
+}
+function emitToSubscribers(taskId, event) {
+  const buffer = state.buffers.get(taskId);
+  if (buffer !== void 0) buffer.push(event);
+  const subs = state.subscribers.get(taskId);
+  if (subs === void 0) return;
+  for (const cb of subs) {
+    try {
+      cb(event);
+    } catch (err) {
+      process.stderr.write(`[task] subscriber threw: ${err.message}
+`);
+    }
+  }
+}
+async function safeUpdate(taskId, mutate) {
+  try {
+    return await state.store.update(taskId, mutate);
+  } catch (err) {
+    process.stderr.write(`[task] store.update failed for ${taskId}: ${err.message}
+`);
+    return void 0;
+  }
+}
+function startEvictTimerIfNeeded() {
+  if (state.evictTimer !== void 0) return;
+  state.evictTimer = setInterval(() => {
+    const cutoff = Date.now() - state.retentionMs;
+    void state.store.evictTerminalOlderThan(cutoff).then((count) => {
+      if (count === 0) return;
+      for (const id of state.buffers.keys()) {
+        void state.store.get(id).then((h) => {
+          if (h === void 0) {
+            state.buffers.delete(id);
+            state.subscribers.delete(id);
+            state.aborters.delete(id);
+          }
+        });
+      }
+    }).catch(() => {
+    });
+  }, EVICTION_INTERVAL_MS).unref();
+}
+function buildSubmittedEvent(handle) {
+  return {
+    type: "submitted",
+    taskId: handle.id,
+    kind: handle.kind,
+    submittedAt: handle.submittedAt,
+    ...handle.meta !== void 0 ? { meta: handle.meta } : {}
+  };
+}
+async function shortCircuitAborted(handle, signal) {
+  const cancelled = {
+    ...handle,
+    state: "cancelled",
+    cancelledAt: Date.now()
+  };
+  await state.store.insert(cancelled);
+  state.buffers.set(handle.id, new RingBuffer(RING_CAP));
+  emitToSubscribers(handle.id, buildSubmittedEvent(cancelled));
+  emitToSubscribers(handle.id, {
+    type: "cancelled",
+    taskId: handle.id,
+    cancelledAt: cancelled.cancelledAt ?? Date.now(),
+    reason: signal.reason instanceof Error ? signal.reason.message : "pre-aborted"
+  });
+  return cancelled;
+}
+async function transition(taskId, next, patch) {
+  const before = await state.store.get(taskId);
+  const span = startTaskTransitionSpan({
+    taskId,
+    from: before?.state ?? "unknown",
+    to: next
+  });
+  try {
+    await safeUpdate(taskId, (h) => ({ ...h, state: next, ...patch }));
+  } finally {
+    span.end();
+  }
+}
+async function buildAndInsertQueued(internal, resolvedId) {
+  const submittedAt = Date.now();
+  const handle = {
+    id: resolvedId,
+    kind: internal.kind,
+    state: "queued",
+    submittedAt,
+    ...internal.meta !== void 0 ? { meta: internal.meta } : {}
+  };
+  await state.store.insert(handle);
+  state.buffers.set(resolvedId, new RingBuffer(RING_CAP));
+  emitToSubscribers(resolvedId, buildSubmittedEvent(handle));
+  return handle;
+}
+function resolveIdInternal(internal) {
+  if (internal.id === void 0) return crypto.randomUUID();
+  if (!isValidTaskId(internal.id, internal.allowReservedPrefix ?? false)) {
+    throw new InvalidTaskIdError(`invalid task id: ${internal.id}`, internal.id);
+  }
+  return internal.id;
+}
+async function runWorkAndFinalize(taskId, aborter, work) {
+  const ctx = {
+    signal: aborter.signal,
+    emit(payload) {
+      void checkCancelRequestedAt(taskId, aborter);
+      emitToSubscribers(taskId, {
+        type: "progress",
+        taskId,
+        at: Date.now(),
+        payload
+      });
+    }
+  };
+  try {
+    const result = await reentryAls.run(true, () => Promise.resolve().then(() => work(ctx)));
+    if (aborter.signal.aborted) {
+      const cancelledAt = Date.now();
+      await transition(taskId, "cancelled", { cancelledAt });
+      emitToSubscribers(taskId, { type: "cancelled", taskId, cancelledAt });
+      return;
+    }
+    const finishedAt = Date.now();
+    await transition(taskId, "finished", { finishedAt, result });
+    emitToSubscribers(taskId, { type: "finished", taskId, finishedAt, result });
+  } catch (err) {
+    if (aborter.signal.aborted) {
+      const cancelledAt = Date.now();
+      await transition(taskId, "cancelled", { cancelledAt });
+      emitToSubscribers(taskId, { type: "cancelled", taskId, cancelledAt });
+      return;
+    }
+    const erroredAt = Date.now();
+    const error = err instanceof Error ? { code: err.code ?? "work_threw", message: err.message } : { code: "work_threw", message: String(err) };
+    await transition(taskId, "error", { erroredAt, error });
+    emitToSubscribers(taskId, { type: "errored", taskId, erroredAt, error });
+  }
+}
+async function checkCancelRequestedAt(taskId, aborter) {
+  if (aborter.signal.aborted) return;
+  try {
+    const handle = await state.store.get(taskId);
+    if (handle?.cancelRequested === true) {
+      aborter.abort("cancelRequested");
+    }
+  } catch {
+  }
+}
+async function acquireSlot() {
+  if (reentryAls.getStore() === true) {
+    return () => {
+    };
+  }
+  return state.semaphore.acquire();
+}
+async function submit(internal) {
+  state.firstSubmitSeen = true;
+  startEvictTimerIfNeeded();
+  const resolvedId = resolveIdInternal(internal);
+  const submitSpan = startTaskSubmitSpan({ taskId: resolvedId, kind: internal.kind });
+  const existing = await state.store.get(resolvedId);
+  if (existing !== void 0) {
+    submitSpan.end();
+    return existing;
+  }
+  const queuedHandle = await buildAndInsertQueued(internal, resolvedId);
+  submitSpan.end();
+  if (internal.signal?.aborted === true) {
+    return shortCircuitAborted(queuedHandle, internal.signal);
+  }
+  const aborter = new AbortController();
+  state.aborters.set(resolvedId, aborter);
+  if (internal.signal !== void 0) {
+    internal.signal.addEventListener("abort", () => aborter.abort(internal.signal?.reason), {
+      once: true
+    });
+  }
+  const release = await acquireSlot();
+  void (async () => {
+    try {
+      await checkCancelRequestedAt(resolvedId, aborter);
+      if (aborter.signal.aborted) {
+        const cancelledAt = Date.now();
+        await transition(resolvedId, "cancelled", { cancelledAt });
+        emitToSubscribers(resolvedId, { type: "cancelled", taskId: resolvedId, cancelledAt });
+        return;
+      }
+      const startedAt = Date.now();
+      await transition(resolvedId, "running", { startedAt });
+      emitToSubscribers(resolvedId, { type: "started", taskId: resolvedId, startedAt });
+      await runWorkAndFinalize(resolvedId, aborter, internal.work);
+    } finally {
+      release();
+      state.aborters.delete(resolvedId);
+    }
+  })();
+  return queuedHandle;
+}
+async function list(filter = {}) {
+  return state.store.list(filter);
+}
+async function get(id) {
+  if (!isValidTaskId(id, true)) return void 0;
+  return state.store.get(id);
+}
+async function cancel(id, reason) {
+  if (!isValidTaskId(id, true)) return { cancelled: false, alreadyTerminal: false };
+  const handle = await state.store.get(id);
+  if (handle === void 0) return { cancelled: false, alreadyTerminal: false };
+  if (handle.state === "finished" || handle.state === "error" || handle.state === "cancelled") {
+    return { cancelled: false, alreadyTerminal: true };
+  }
+  const span = startTaskCancelSpan({
+    taskId: id,
+    ...reason !== void 0 ? { reason } : {},
+    via: "api"
+  });
+  try {
+    return await cancelInternal(id, handle.state, reason);
+  } finally {
+    span.end();
+  }
+}
+async function cancelInternal(id, currentState, reason) {
+  if (currentState === "queued") {
+    const cancelledAt = Date.now();
+    await transition(id, "cancelled", { cancelledAt });
+    emitToSubscribers(id, {
+      type: "cancelled",
+      taskId: id,
+      cancelledAt,
+      ...reason !== void 0 ? { reason } : {}
+    });
+    state.aborters.delete(id);
+    return { cancelled: true, alreadyTerminal: false };
+  }
+  const aborter = state.aborters.get(id);
+  if (aborter !== void 0) aborter.abort(reason ?? "cancelled");
+  return { cancelled: true, alreadyTerminal: false };
+}
+async function evictNow(now = Date.now()) {
+  return state.store.evictTerminalOlderThan(now - state.retentionMs);
+}
+var DEFAULT_CONCURRENCY, DEFAULT_RETENTION_MS, EVICTION_INTERVAL_MS, RING_CAP, reentryAls, state, subscribe;
+var init_registry = __esm({
+  "src/internal/task/registry.ts"() {
+    init_errors();
+    init_task();
+    init_async_semaphore();
+    init_ring_buffer();
+    init_store();
+    init_subscribe();
+    init_telemetry2();
+    DEFAULT_CONCURRENCY = 8;
+    DEFAULT_RETENTION_MS = 60 * 60 * 1e3;
+    EVICTION_INTERVAL_MS = 5 * 60 * 1e3;
+    RING_CAP = 64;
+    reentryAls = new async_hooks.AsyncLocalStorage();
+    state = buildState({});
+    subscribe = buildSubscribe({
+      getBuffer: (id) => state.buffers.get(id),
+      getOrCreateSubscriberSet: (id) => {
+        let subs = state.subscribers.get(id);
+        if (subs === void 0) {
+          subs = /* @__PURE__ */ new Set();
+          state.subscribers.set(id, subs);
+        }
+        return subs;
+      },
+      removeSubscriber: (id, cb) => {
+        const set = state.subscribers.get(id);
+        set?.delete(cb);
+        if (set !== void 0 && set.size === 0) state.subscribers.delete(id);
+      }
+    });
+  }
+});
+var PersistenceSchema = zod.z.object({
+  backend: zod.z.enum(["memory", "json"]),
+  dir: zod.z.string().optional()
+}).refine((p) => p.backend !== "json" || typeof p.dir === "string" && p.dir.length > 0, {
+  message: 'persistence.dir is required when backend = "json"'
+}).optional();
+
+// src/internal/security/path-guard.ts
+init_errors();
+var IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9\-_]*$/i;
+function sanitizeIdentifier(input, options) {
+  const maxLen = options?.maxLen;
+  if (input.length === 0 || input.length > maxLen) {
+    throw new ConfigurationError(`Identifier length out of range (1-${maxLen}): "${input}"`, {
+      code: "invalid_identifier"
+    });
+  }
+  if (!IDENTIFIER_PATTERN.test(input)) {
+    throw new ConfigurationError(`Identifier contains invalid characters: "${input}"`, {
+      code: "invalid_identifier"
+    });
+  }
+  return input.toLowerCase();
+}
+
+// src/workflow.ts
+init_workflow();
+init_snapshot_store();
+init_workflow();
+var RetryPolicySchema = zod.z.object({
+  // EC-3 absorbed: maxAttempts MUST be a finite int in [1, 20].
+  maxAttempts: zod.z.number().int("retry.maxAttempts must be integer").min(1, "retry.maxAttempts must be >= 1").max(20, "retry.maxAttempts must be <= 20"),
+  initialBackoffMs: zod.z.number().int().min(0).optional(),
+  backoffCoefficient: zod.z.number().min(1).optional(),
+  maximumBackoffMs: zod.z.number().int().min(0).optional(),
+  nonRetryableErrors: zod.z.array(zod.z.string()).optional()
+});
+var WorkflowOptionsSchema = zod.z.object({
+  name: zod.z.string().min(1).max(128),
+  persistence: PersistenceSchema
+});
+var WorkflowBuilder = class {
+  /** @internal */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  _steps = [];
+  _committed = false;
+  /** @internal — only the executor reads this. */
+  get __steps() {
+    return this._steps;
+  }
+  // biome-ignore lint/suspicious/noThenProperty: D233 locks the Mastra-style `.then(step)` builder DSL. The method is fluent, never awaited.
+  then(step) {
+    this.assertNotCommitted();
+    validateStepId(step.id);
+    this._steps.push(step);
+    return this;
+  }
+  parallel(branches, opts) {
+    this.assertNotCommitted();
+    const id = opts?.id ?? `parallel_${this._steps.length}`;
+    validateStepId(id);
+    for (const branch of branches) {
+      for (const inner of branch) validateStepId(inner.id);
+    }
+    const step = {
+      kind: "parallel",
+      id,
+      branches,
+      ...opts?.concurrency !== void 0 ? { concurrency: opts.concurrency } : {},
+      ...opts?.errorPolicy !== void 0 ? { errorPolicy: opts.errorPolicy } : {}
+    };
+    this._steps.push(step);
+    return this;
+  }
+  branch(predicates, opts) {
+    this.assertNotCommitted();
+    const id = opts?.id ?? `branch_${this._steps.length}`;
+    validateStepId(id);
+    const step = {
+      kind: "branch",
+      id,
+      predicates,
+      ...opts?.fallback !== void 0 ? { fallback: opts.fallback } : {}
+    };
+    this._steps.push(step);
+    return this;
+  }
+  foreach(iterableFrom, step, opts) {
+    this.assertNotCommitted();
+    const id = opts?.id ?? `foreach_${this._steps.length}`;
+    validateStepId(id);
+    validateStepId(iterableFrom);
+    validateStepId(step.id);
+    const node = {
+      kind: "foreach",
+      id,
+      iterableFrom,
+      step,
+      ...opts?.concurrency !== void 0 ? { concurrency: opts.concurrency } : {}
+    };
+    this._steps.push(node);
+    return this;
+  }
+  dowhile(step, condFn, opts) {
+    this.assertNotCommitted();
+    const id = opts?.id ?? `dowhile_${this._steps.length}`;
+    validateStepId(id);
+    validateStepId(step.id);
+    const node = {
+      kind: "dowhile",
+      id,
+      step,
+      condFn,
+      ...opts?.maxIterations !== void 0 ? { maxIterations: opts.maxIterations } : {}
+    };
+    this._steps.push(node);
+    return this;
+  }
+  sleep(durationMs, id) {
+    this.assertNotCommitted();
+    const stepId = id ?? `sleep_${this._steps.length}`;
+    validateStepId(stepId);
+    if (!Number.isFinite(durationMs) || durationMs < 0) {
+      throw new Error(`sleep durationMs must be finite non-negative: ${durationMs}`);
+    }
+    const step = { kind: "sleep", id: stepId, durationMs };
+    this._steps.push(step);
+    return this;
+  }
+  suspend(opts) {
+    this.assertNotCommitted();
+    const id = opts?.id ?? `suspend_${this._steps.length}`;
+    validateStepId(id);
+    const step = {
+      kind: "suspend",
+      id,
+      ...opts?.payloadSchema !== void 0 ? { payloadSchema: opts.payloadSchema } : {}
+    };
+    this._steps.push(step);
+    return this;
+  }
+  commit() {
+    this.assertNotCommitted();
+    this.validateUniqueIds();
+    this._committed = true;
+    const workflowId = `wf-${mintShortId()}`;
+    return new Workflow({ ...this.options, workflowId }, [...this._steps]);
+  }
+  validateUniqueIds() {
+    const seen = /* @__PURE__ */ new Set();
+    walkStepsValidating(this._steps, seen);
+  }
+  assertNotCommitted() {
+    if (this._committed) {
+      throw new Error("Workflow already committed; create a fresh Workflow.create(...) call.");
+    }
+  }
+};
+var Workflow = class {
+  /** @internal */
+  constructor(_options, _steps) {
+    this._options = _options;
+    this._steps = _steps;
+  }
+  _options;
+  _steps;
+  /** @internal — only the executor reads these. */
+  get __options() {
+    return this._options;
+  }
+  /** @internal */
+  get __steps() {
+    return this._steps;
+  }
+  /**
+   * Construct a workflow builder. Validate options via Zod and return a
+   * `WorkflowBuilder` for fluent chaining. Call `.commit()` to obtain the
+   * immutable `Workflow`.
+   */
+  static create(options) {
+    WorkflowOptionsSchema.parse(options);
+    return new WorkflowBuilder(options);
+  }
+  /**
+   * Run this workflow with the given input. Returns a populated
+   * `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via
+   * `run.status === "failed"`.
+   */
+  async run(input, opts) {
+    const { executeWorkflow: executeWorkflow2 } = await Promise.resolve().then(() => (init_executor(), executor_exports));
+    const result = await executeWorkflow2(this._options, this._steps, input, opts);
+    if (opts?.task !== void 0) {
+      const { submit: taskSubmit } = await Promise.resolve().then(() => (init_registry(), registry_exports));
+      const taskOpts = opts.task === true ? {} : opts.task;
+      const id = taskOpts.id ?? `wf-${result.id}`;
+      await taskSubmit({
+        kind: "workflow",
+        work: async (ctx) => {
+          ctx.emit({ status: result.status, runId: result.id });
+          return { status: result.status, runId: result.id, output: result.output };
+        },
+        id,
+        meta: {
+          workflowName: this._options.name,
+          runId: result.id,
+          status: result.status,
+          ...taskOpts.meta ?? {}
+        },
+        allowReservedPrefix: true
+      });
+    }
+    return result;
+  }
+  /**
+   * Resume a suspended workflow from its snapshot. Throws
+   * `WorkflowSnapshotNotFoundError` if `runId` is unknown.
+   */
+  static async resume(opts) {
+    const { resumeWorkflow: resumeWorkflow2 } = await Promise.resolve().then(() => (init_executor(), executor_exports));
+    return resumeWorkflow2(opts);
+  }
+};
+function fn(id, step, opts) {
+  validateStepId(id);
+  if (opts?.retry !== void 0) RetryPolicySchema.parse(opts.retry);
+  return {
+    kind: "fn",
+    id,
+    fn: step,
+    ...opts?.inputSchema !== void 0 ? { inputSchema: opts.inputSchema } : {},
+    ...opts?.outputSchema !== void 0 ? { outputSchema: opts.outputSchema } : {},
+    ...opts?.retry !== void 0 ? { retry: opts.retry } : {}
+  };
+}
+function agentStep(id, agent, promptTemplate, opts) {
+  validateStepId(id);
+  if (opts?.retry !== void 0) RetryPolicySchema.parse(opts.retry);
+  return {
+    kind: "agent",
+    id,
+    agent,
+    promptTemplate,
+    ...opts?.retry !== void 0 ? { retry: opts.retry } : {}
+  };
+}
+function validateStepId(id) {
+  sanitizeIdentifier(id, { maxLen: 64 });
+}
+function mintShortId() {
+  return globalThis.crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+}
+function nestedStepsOf(s) {
+  if (s.kind === "parallel") return s.branches;
+  if (s.kind === "branch") {
+    const groups = s.predicates.map(([, branch]) => branch);
+    return s.fallback !== void 0 ? [...groups, s.fallback] : groups;
+  }
+  if (s.kind === "foreach" || s.kind === "dowhile") return [[s.step]];
+  return [];
+}
+function walkStepsValidating(steps, seen) {
+  for (const s of steps) {
+    if (seen.has(s.id)) throw new exports.WorkflowDuplicateStepIdError(s.id);
+    seen.add(s.id);
+    for (const nested of nestedStepsOf(s)) {
+      walkStepsValidating(nested, seen);
+    }
+  }
+}
+
+exports.Workflow = Workflow;
+exports.WorkflowBuilder = WorkflowBuilder;
+exports.__resetSnapshotStoresForTests = __resetSnapshotStoresForTests;
+exports.agentStep = agentStep;
+exports.fn = fn;
+//# sourceMappingURL=workflow.cjs.map
+//# sourceMappingURL=workflow.cjs.map