@stigmer/runner 3.0.1

package/src/workflow-engine/resolve.ts

@@ -0,0 +1,342 @@
+/**
+ * Shared expression resolution utilities for task builders.
+ *
+ * Extracts the expression collection and substitution logic that was
+ * originally embedded in set.ts into reusable functions. All call task
+ * builders (call:http, call:grpc, call:function) use these to evaluate
+ * `${ ... }` expressions in their `with` config before scheduling
+ * Temporal activities.
+ *
+ * Two-phase evaluation (security pattern from Go):
+ * 1. Workflow side: resolve `${ $context.field }` etc. via these utilities
+ * 2. Activity side: resolve `${.secrets.KEY}` just-in-time (never in history)
+ */
+
+import type { ExpressionEvaluator, WorkflowState } from "./types.js";
+import { deepClone } from "./clone.js";
+import {
+  extractEmbeddedExpressions,
+  isStrictExpr,
+  stringifyInterpolatedValue,
+} from "./expression-utils.js";
+
+/**
+ * Resolves all `${ ... }` expressions in a config object using a
+ * two-phase pipeline:
+ *
+ * **Phase 1 — Strict expressions** (existing): whole-value `${ expr }`
+ * strings are collected, batch-evaluated, and substituted.
+ *
+ * **Phase 2 — Embedded expressions** (CNCF spec compliant): strings
+ * containing `${ expr }` fragments within larger text are collected,
+ * batch-evaluated, and interpolated. This enables multi-line agent
+ * messages, LLM prompts, and notification bodies with inline variable
+ * references — as demonstrated in the official CNCF Serverless Workflow
+ * 1.0.0 spec reference examples.
+ *
+ * Each phase produces at most one Temporal local activity call (batch
+ * evaluation). Phase 2 is skipped when no embedded expressions exist.
+ */
+export async function resolveConfigExpressions(
+  config: Record<string, unknown>,
+  input: unknown,
+  state: WorkflowState,
+  evaluateExpressions: ExpressionEvaluator,
+): Promise<Record<string, unknown>> {
+  const cloned = deepClone(config);
+  const stateVars = state.getAsMap();
+
+  // Phase 1: Strict expressions (whole-value `${ expr }`)
+  const strictExprs = collectExpressions(cloned);
+  let phase1Paths: Set<string> = new Set();
+  if (Object.keys(strictExprs).length > 0) {
+    const strictResults = await evaluateExpressions(strictExprs, input, stateVars);
+    substituteResults(cloned, strictResults);
+    phase1Paths = new Set(Object.keys(strictExprs));
+  }
+
+  // Phase 2: Embedded expressions (`"text ${ expr } more text"`)
+  // Skip paths already resolved in Phase 1 to prevent expression injection —
+  // Phase 1 results may contain `${ ... }` patterns from external data
+  // (webhook payloads, API responses) that must NOT be re-interpreted.
+  await resolveEmbeddedExpressions(cloned, input, stateVars, evaluateExpressions, phase1Paths);
+
+  return cloned;
+}
+
+/**
+ * Collects all string expressions (`${ ... }`) from a nested object
+ * into a flat map keyed by their JSON path. Non-expression strings
+ * and non-string values are skipped.
+ */
+export function collectExpressions(
+  obj: Record<string, unknown>,
+  prefix = "",
+): Record<string, string> {
+  const expressions: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+
+    if (typeof value === "string" && value.startsWith("${ ") && value.endsWith(" }")) {
+      expressions[path] = value.slice(3, -2);
+    } else if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      Object.assign(
+        expressions,
+        collectExpressions(value as Record<string, unknown>, path),
+      );
+    } else if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const itemPath = `${path}[${i}]`;
+        if (typeof value[i] === "string" && value[i].startsWith("${ ") && value[i].endsWith(" }")) {
+          expressions[itemPath] = value[i].slice(3, -2);
+        } else if (value[i] !== null && typeof value[i] === "object") {
+          Object.assign(
+            expressions,
+            collectExpressions(value[i] as Record<string, unknown>, itemPath),
+          );
+        }
+      }
+    }
+  }
+
+  return expressions;
+}
+
+/**
+ * Substitutes evaluated expression results back into the original
+ * object structure. Expression paths (e.g., "body.userId") are
+ * resolved to their positions in the object tree.
+ */
+export function substituteResults(
+  obj: Record<string, unknown>,
+  results: Record<string, unknown>,
+): Record<string, unknown> {
+  for (const [path, value] of Object.entries(results)) {
+    setNestedValue(obj, path, value);
+  }
+  return obj;
+}
+
+function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = parsePath(path);
+  let current: unknown = obj;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (typeof part === "number") {
+      current = (current as unknown[])[part];
+    } else {
+      current = (current as Record<string, unknown>)[part];
+    }
+  }
+
+  const lastPart = parts[parts.length - 1];
+  if (typeof lastPart === "number") {
+    (current as unknown[])[lastPart] = value;
+  } else {
+    (current as Record<string, unknown>)[lastPart] = value;
+  }
+}
+
+function parsePath(path: string): (string | number)[] {
+  const parts: (string | number)[] = [];
+  const segments = path.split(".");
+
+  for (const segment of segments) {
+    const bracketMatch = segment.match(/^(.+?)\[(\d+)\]$/);
+    if (bracketMatch) {
+      parts.push(bracketMatch[1]);
+      parts.push(Number(bracketMatch[2]));
+    } else {
+      parts.push(segment);
+    }
+  }
+
+  return parts;
+}
+
+const RUNTIME_PLACEHOLDER_RE = /\$\{\.(secrets|env_vars)\.\w+\}/;
+
+/**
+ * Checks whether a string contains a runtime placeholder that should
+ * NOT be evaluated in the workflow (deterministic) phase. These are
+ * resolved just-in-time in the activity where secrets are available.
+ *
+ * Pattern: `${.secrets.KEY}` or `${.env_vars.KEY}`
+ * (no space after `${` — distinguishes from jq expressions `${ ... }`)
+ */
+export function isRuntimePlaceholder(value: string): boolean {
+  return RUNTIME_PLACEHOLDER_RE.test(value);
+}
+
+/**
+ * Resolves runtime placeholders (`${.secrets.KEY}`, `${.env_vars.KEY}`)
+ * in a string using values from the runtime environment map.
+ *
+ * This runs in activities only — never in the workflow sandbox.
+ */
+export function resolveRuntimePlaceholders(
+  value: string,
+  runtimeEnv: Record<string, unknown>,
+): string {
+  return value.replace(
+    /\$\{\.(secrets|env_vars)\.(\w+)\}/g,
+    (_match, _ns: string, key: string) => {
+      const resolved = runtimeEnv[key];
+      return resolved !== undefined ? String(resolved) : "";
+    },
+  );
+}
+
+/**
+ * Recursively resolves all runtime placeholders in a nested object.
+ * Walks maps, arrays, and strings. Non-string leaves pass through.
+ */
+export function resolveObjectPlaceholders(
+  obj: unknown,
+  runtimeEnv: Record<string, unknown>,
+): unknown {
+  if (typeof obj === "string") {
+    return resolveRuntimePlaceholders(obj, runtimeEnv);
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveObjectPlaceholders(item, runtimeEnv));
+  }
+  if (obj !== null && typeof obj === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+      result[key] = resolveObjectPlaceholders(value, runtimeEnv);
+    }
+    return result;
+  }
+  return obj;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Embedded Expression Resolution (Phase 2)
+// ─────────────────────────────────────────────────────────────────────
+
+interface EmbeddedExprMapping {
+  /** JSON path to the string field in the config object. */
+  path: string;
+  /** Ordered list of expressions found in that string. */
+  expressions: Array<{ start: number; end: number; expr: string }>;
+}
+
+/**
+ * Resolves embedded `${ ... }` expressions within string values of a
+ * config object. Strings where the entire value is a strict expression
+ * are skipped (already handled in Phase 1). Only strings containing
+ * `${ ... }` fragments within larger text are processed.
+ *
+ * All embedded expressions across all fields are collected and
+ * evaluated in a single batch call to the expression evaluator,
+ * preserving the Temporal local activity batch optimization.
+ *
+ * Mutates `obj` in place. Returns early if no embedded expressions
+ * are found (zero overhead for strict-only workflows).
+ *
+ * @param skipPaths - Paths already resolved in Phase 1 whose string
+ *   results must not be re-interpolated (prevents expression injection
+ *   from external data flowing through `$context`).
+ */
+export async function resolveEmbeddedExpressions(
+  obj: Record<string, unknown>,
+  input: unknown,
+  stateVars: Record<string, unknown>,
+  evaluateExpressions: ExpressionEvaluator,
+  skipPaths: Set<string> = new Set(),
+): Promise<void> {
+  const mappings: EmbeddedExprMapping[] = [];
+  const batchExprs: Record<string, string> = {};
+
+  collectEmbeddedExpressions(obj, "", mappings, batchExprs, skipPaths);
+
+  if (Object.keys(batchExprs).length === 0) return;
+
+  const results = await evaluateExpressions(batchExprs, input, stateVars);
+
+  for (const mapping of mappings) {
+    const original = getNestedValue(obj, mapping.path) as string;
+    let interpolated = "";
+    let lastEnd = 0;
+
+    for (let i = 0; i < mapping.expressions.length; i++) {
+      const embedded = mapping.expressions[i];
+      // Tilde cannot appear in dot/bracket JSON paths, so it's unambiguous as a separator.
+      const key = `${mapping.path}~${i}`;
+      interpolated += original.slice(lastEnd, embedded.start);
+      interpolated += stringifyInterpolatedValue(results[key]);
+      lastEnd = embedded.end;
+    }
+
+    interpolated += original.slice(lastEnd);
+    setNestedValue(obj, mapping.path, interpolated);
+  }
+}
+
+/**
+ * Walks the object tree collecting embedded expressions from string
+ * values into the batch map. Each expression gets a composite key
+ * `path~index` so results can be mapped back to their source strings.
+ */
+function collectEmbeddedExpressions(
+  obj: Record<string, unknown>,
+  prefix: string,
+  mappings: EmbeddedExprMapping[],
+  batchExprs: Record<string, string>,
+  skipPaths: Set<string>,
+): void {
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    collectEmbeddedFromValue(value, path, mappings, batchExprs, skipPaths);
+  }
+}
+
+function collectEmbeddedFromValue(
+  value: unknown,
+  path: string,
+  mappings: EmbeddedExprMapping[],
+  batchExprs: Record<string, string>,
+  skipPaths: Set<string>,
+): void {
+  if (typeof value === "string") {
+    if (skipPaths.has(path)) return;
+    if (isStrictExpr(value)) return;
+    const expressions = extractEmbeddedExpressions(value);
+    if (expressions.length === 0) return;
+
+    mappings.push({ path, expressions });
+    for (let i = 0; i < expressions.length; i++) {
+      batchExprs[`${path}~${i}`] = expressions[i].expr;
+    }
+  } else if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      collectEmbeddedFromValue(value[i], `${path}[${i}]`, mappings, batchExprs, skipPaths);
+    }
+  } else if (value !== null && typeof value === "object") {
+    collectEmbeddedExpressions(
+      value as Record<string, unknown>,
+      path,
+      mappings,
+      batchExprs,
+      skipPaths,
+    );
+  }
+}
+
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const parts = parsePath(path);
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (typeof part === "number") {
+      current = (current as unknown[])[part];
+    } else {
+      current = (current as Record<string, unknown>)[part];
+    }
+  }
+
+  return current;
+}

package/src/workflow-engine/retry.ts

@@ -0,0 +1,109 @@
+/**
+ * Retry delay calculator for CNCF Serverless Workflow catch-level retry.
+ *
+ * Pure, deterministic functions that compute the delay (in milliseconds)
+ * for a given retry attempt based on the retry policy configuration.
+ * No side effects, no Temporal imports, no Node.js dependencies.
+ *
+ * Supports three backoff strategies:
+ * - constant: delay stays the same every attempt
+ * - exponential: delay doubles each attempt (delay * 2^(attempt-1))
+ * - linear: delay grows linearly (delay * attempt)
+ *
+ * Jitter adds a random offset in [from, to] to the computed delay.
+ * Math.random() is used for jitter — Temporal's sandbox replaces it
+ * with a deterministic PRNG, so jitter values replay identically.
+ *
+ * @module
+ */
+
+import type { RetryConfig, BackoffConfig } from "./types.js";
+import { durationToMs } from "./duration.js";
+
+const DEFAULT_BASE_DELAY_MS = 1_000;
+
+/**
+ * Computes the delay in milliseconds for a retry attempt, or returns
+ * `null` if the retry limits have been exceeded and no more retries
+ * should be attempted.
+ *
+ * @param attempt - 1-indexed retry attempt number (1 = first retry)
+ * @param config - the retry policy from `catch.retry`
+ * @param elapsedMs - cumulative delay already spent on prior retries
+ * @returns delay in ms, or `null` if limits exceeded
+ */
+export function computeRetryDelay(
+  attempt: number,
+  config: RetryConfig,
+  elapsedMs: number,
+): number | null {
+  if (exceedsAttemptLimit(attempt, config)) return null;
+
+  const baseMs = resolveBaseDelay(config);
+  const multiplier = resolveBackoffMultiplier(attempt, config.backoff);
+  let delay = baseMs * multiplier;
+
+  delay += resolveJitter(config);
+
+  delay = Math.max(0, Math.round(delay));
+
+  if (exceedsDurationLimit(elapsedMs + delay, config)) return null;
+
+  return delay;
+}
+
+function exceedsAttemptLimit(attempt: number, config: RetryConfig): boolean {
+  const maxAttempts = config.limit?.attempt?.count;
+  if (maxAttempts !== undefined && attempt > maxAttempts) return true;
+  return false;
+}
+
+function exceedsDurationLimit(totalMs: number, config: RetryConfig): boolean {
+  if (!config.limit?.duration) return false;
+  const maxMs = durationToMs(config.limit.duration);
+  return maxMs > 0 && totalMs > maxMs;
+}
+
+/**
+ * Resolves the base delay from config.delay. When backoff is specified
+ * but no explicit delay, defaults to 1 second — multiplying zero by a
+ * backoff factor is never useful.
+ */
+function resolveBaseDelay(config: RetryConfig): number {
+  if (config.delay) return durationToMs(config.delay);
+  if (config.backoff) return DEFAULT_BASE_DELAY_MS;
+  return 0;
+}
+
+/**
+ * Computes the backoff multiplier for the given attempt.
+ *
+ * - constant: multiplier is always 1 (delay stays the same)
+ * - exponential: 2^(attempt-1) — 1x, 2x, 4x, 8x, ...
+ * - linear: attempt — 1x, 2x, 3x, 4x, ...
+ * - no backoff: multiplier is 1
+ */
+function resolveBackoffMultiplier(
+  attempt: number,
+  backoff: BackoffConfig | undefined,
+): number {
+  if (!backoff) return 1;
+  if (backoff.exponential) return Math.pow(2, attempt - 1);
+  if (backoff.linear) return attempt;
+  return 1;
+}
+
+/**
+ * Computes jitter as a random value in [from, to] milliseconds.
+ * When jitter is not configured, returns 0.
+ */
+function resolveJitter(config: RetryConfig): number {
+  if (!config.jitter) return 0;
+
+  const fromMs = config.jitter.from ? durationToMs(config.jitter.from) : 0;
+  const toMs = config.jitter.to ? durationToMs(config.jitter.to) : 0;
+
+  if (toMs <= fromMs) return fromMs;
+
+  return fromMs + Math.random() * (toMs - fromMs);
+}

package/src/workflow-engine/state.ts

@@ -0,0 +1,56 @@
+/**
+ * Workflow execution state — the data bag that flows through the
+ * task chain, carrying accumulated results, environment variables,
+ * original input, and the current output value.
+ *
+ * Mirrors Go's `utils.State` struct. The five namespaces ($context,
+ * $data, $env, $input, $output) are exposed to jq expressions via
+ * `getAsMap()`.
+ */
+
+import type { WorkflowState as IWorkflowState } from "./types.js";
+import { deepClone } from "./clone.js";
+
+export class WorkflowStateImpl implements IWorkflowState {
+  context: unknown = null;
+  data: Record<string, unknown> = {};
+  env: Record<string, unknown> = {};
+  input: unknown = null;
+  output: unknown = null;
+
+  addData(data: Record<string, unknown>): void {
+    Object.assign(this.data, data);
+  }
+
+  /**
+   * Returns the state as a flat map of jq variable bindings.
+   * Each key becomes a jq variable (e.g., `$context`, `$data`).
+   */
+  getAsMap(): Record<string, unknown> {
+    return {
+      $context: deepClone(this.context),
+      $data: deepClone(this.data),
+      $env: deepClone(this.env),
+      $input: deepClone(this.input),
+      $output: deepClone(this.output),
+    };
+  }
+
+  clone(): WorkflowStateImpl {
+    const s = new WorkflowStateImpl();
+    s.context = deepClone(this.context);
+    s.data = deepClone(this.data) as Record<string, unknown>;
+    s.env = deepClone(this.env) as Record<string, unknown>;
+    s.input = deepClone(this.input);
+    s.output = deepClone(this.output);
+    return s;
+  }
+
+  clearOutput(): void {
+    this.output = null;
+  }
+}
+
+export function createState(): WorkflowStateImpl {
+  return new WorkflowStateImpl();
+}

package/src/workflow-engine/task-factory.ts

@@ -0,0 +1,160 @@
+/**
+ * Task builder factory — creates the appropriate TaskBuilder for a
+ * given task definition based on the `kind` discriminator.
+ *
+ * Phases 1–2: set, switch, do (nested), for (iteration).
+ * Phase 4: call:http, call:grpc, call:function (llm, etc.).
+ * Phase 4b: call:agent (async completion, HITL signals).
+ * Phase 5.1: raise (error throwing), try (placeholder — execution in do-executor).
+ * Phase 5.2: fork (parallel branches — execution in do-executor).
+ *
+ * Mirrors Go's `NewTaskBuilder` type switch in `task_builder.go`.
+ */
+
+import type { TaskDef, TaskBuilder, WorkflowModel } from "./types.js";
+import { SetTaskBuilder } from "./tasks/set.js";
+import { SwitchTaskBuilder } from "./tasks/switch.js";
+import { ForTaskPlaceholderBuilder } from "./tasks/for.js";
+import { ForkTaskPlaceholderBuilder } from "./tasks/fork.js";
+import { TryTaskPlaceholderBuilder } from "./tasks/try.js";
+import { RaiseTaskBuilder } from "./tasks/raise.js";
+import { WaitTaskBuilder } from "./tasks/wait.js";
+import { RunTaskBuilder } from "./tasks/run.js";
+import { CallHttpTaskBuilder } from "./tasks/call-http.js";
+import { CallGrpcTaskBuilder } from "./tasks/call-grpc.js";
+import { CallAgentTaskBuilder } from "./tasks/call-agent.js";
+import { CallFunctionTaskBuilder } from "./tasks/call-function.js";
+
+export function createTaskBuilder(
+  taskName: string,
+  taskDef: TaskDef,
+  _doc: WorkflowModel,
+): TaskBuilder {
+  switch (taskDef.kind) {
+    case "set":
+      return new SetTaskBuilder(taskName, taskDef);
+    case "switch":
+      return new SwitchTaskBuilder(taskName, taskDef);
+    case "do":
+      return new DoTaskPlaceholderBuilder(taskName, taskDef);
+    case "for":
+      return new ForTaskPlaceholderBuilder(taskName, taskDef);
+    case "fork":
+      return new ForkTaskPlaceholderBuilder(taskName, taskDef);
+    case "try":
+      return new TryTaskPlaceholderBuilder(taskName, taskDef);
+    case "raise":
+      return new RaiseTaskBuilder(taskName, taskDef);
+    case "wait":
+      return new WaitTaskBuilder(taskName, taskDef);
+    case "listen":
+      return new ListenTaskPlaceholderBuilder(taskName, taskDef);
+    case "human_input":
+      return new HumanInputTaskPlaceholderBuilder(taskName, taskDef);
+    case "run":
+      return new RunTaskBuilder(taskName, taskDef);
+    case "call:http":
+      return new CallHttpTaskBuilder(taskName, taskDef);
+    case "call:grpc":
+      return new CallGrpcTaskBuilder(taskName, taskDef);
+    case "call:agent":
+      return new CallAgentTaskBuilder(taskName, taskDef);
+    case "call:function":
+      return new CallFunctionTaskBuilder(taskName, taskDef);
+    default:
+      throw new Error(
+        `Unsupported task type '${(taskDef as TaskDef).kind}' for task '${taskName}'. ` +
+        `Supported: set, switch, do, for, fork, try, raise, wait, listen, run, call:http, call:grpc, call:agent, call:function. ` +
+        `Other types will be added in later phases.`,
+      );
+  }
+}
+
+/**
+ * Placeholder builder for nested `do` tasks. The actual execution
+ * is handled by the DoTask executor via recursion — this builder
+ * exists only to satisfy the TaskBuilder interface in the task list.
+ */
+class DoTaskPlaceholderBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: TaskDef;
+
+  constructor(taskName: string, taskDef: TaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build() {
+    return async () => {
+      throw new Error(
+        `DoTaskPlaceholderBuilder.build() should never be called directly. ` +
+        `The executor handles 'do' tasks via recursion.`,
+      );
+    };
+  }
+
+  async shouldRun() {
+    return true;
+  }
+}
+
+/**
+ * Placeholder builder for `listen` tasks. Execution is handled by
+ * the dedicated `executeListenTask` function in do-executor.
+ */
+class ListenTaskPlaceholderBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: TaskDef;
+
+  constructor(taskName: string, taskDef: TaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build() {
+    return async () => {
+      throw new Error(
+        `ListenTaskPlaceholderBuilder.build() should never be called directly. ` +
+        `The executor handles 'listen' tasks via the listen orchestrator.`,
+      );
+    };
+  }
+
+  async shouldRun() {
+    return true;
+  }
+}
+
+/**
+ * Placeholder builder for `human_input` tasks. Execution is handled by
+ * the dedicated `executeHumanInputTask` function in do-executor.
+ */
+class HumanInputTaskPlaceholderBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: TaskDef;
+
+  constructor(taskName: string, taskDef: TaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build() {
+    return async () => {
+      throw new Error(
+        `HumanInputTaskPlaceholderBuilder.build() should never be called directly. ` +
+        `The executor handles 'human_input' tasks via the HITL orchestrator.`,
+      );
+    };
+  }
+
+  async shouldRun() {
+    return true;
+  }
+}
+
+export const DO_TASK_KIND = "do" as const;
+export const FOR_TASK_KIND = "for" as const;
+export const FORK_TASK_KIND = "fork" as const;
+export const TRY_TASK_KIND = "try" as const;
+export const LISTEN_TASK_KIND = "listen" as const;
+export const HUMAN_INPUT_TASK_KIND = "human_input" as const;