@stigmer/runner 3.0.1

package/src/workflow-engine/tasks/call-http.ts

@@ -0,0 +1,51 @@
+/**
+ * CallHTTP task builder — evaluates expressions in the HTTP call
+ * config, then delegates the actual HTTP request to a Temporal
+ * activity via the `ctx.callHttp` callback.
+ *
+ * Mirrors Go's `task_builder_call_http.go` workflow-side logic.
+ *
+ * Two-phase evaluation:
+ * 1. Here (workflow): resolve `${ $context.field }` jq expressions
+ * 2. Activity: resolve `${.secrets.KEY}` runtime placeholders
+ */
+
+import type {
+  CallHttpTaskDef,
+  HttpCallConfig,
+  TaskBuilder,
+  TaskExecutorFn,
+} from "../types.js";
+import { resolveConfigExpressions } from "../resolve.js";
+
+export class CallHttpTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: CallHttpTaskDef;
+
+  constructor(taskName: string, taskDef: CallHttpTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build(): TaskExecutorFn {
+    return async (input, state, ctx) => {
+      const resolved = await resolveConfigExpressions(
+        this.taskDef.with as unknown as Record<string, unknown>,
+        input,
+        state,
+        ctx.evaluateExpressions,
+      );
+
+      const result = await ctx.callHttp(
+        resolved as unknown as HttpCallConfig,
+        state.env,
+      );
+
+      return result;
+    };
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+}

package/src/workflow-engine/tasks/for.ts

@@ -0,0 +1,244 @@
+/**
+ * ForTask executor — iterates over a collection, executing a nested
+ * `do` block for each element. Returns an ordered array of per-iteration
+ * results.
+ *
+ * Mirrors Go's `ForTaskBuilder` in `task_builder_for.go`. The key
+ * behaviors replicated here:
+ *
+ * - Collection evaluated once up front via jq (null input, state vars)
+ * - Per-iteration state cloned from parent snapshot (state.clone().clearOutput())
+ * - Iteration variables bound into $data via addData()
+ * - Body executed through recursive executeDoTasks()
+ * - Optional `while` condition checked per iteration (after variable binding)
+ * - Result is an ordered array of per-iteration outputs
+ *
+ * T17 parallelism (max_parallelism, batch_size, on_error) is deferred
+ * to a future phase — sequential execution only.
+ */
+
+import type {
+  ForTaskDef,
+  WorkflowModel,
+  WorkflowState,
+  ExpressionEvaluator,
+  TaskExecutionContext,
+  TaskBuilder,
+  TaskDef,
+} from "../types.js";
+
+/**
+ * Lazy import of executeDoTasks to break the circular dependency:
+ * do-executor.ts → tasks/for.ts → do-executor.ts.
+ *
+ * The function is resolved on first call and cached.
+ */
+let _executeDoTasks: typeof import("../do-executor.js").executeDoTasks | null = null;
+
+async function getExecuteDoTasks() {
+  if (_executeDoTasks === null) {
+    const mod = await import("../do-executor.js");
+    _executeDoTasks = mod.executeDoTasks;
+  }
+  return _executeDoTasks;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Core Execution
+// ─────────────────────────────────────────────────────────────────────
+
+interface IterItem {
+  readonly key: unknown;
+  readonly value: unknown;
+}
+
+/**
+ * Executes a `for` task — the sequential iteration engine.
+ *
+ * Called directly by the do-executor's `runSingleTask()` when it
+ * encounters a task with `kind: "for"`.
+ */
+export async function executeForTask(
+  taskDef: ForTaskDef,
+  input: unknown,
+  state: WorkflowState,
+  doc: WorkflowModel,
+  evaluateExpressions: ExpressionEvaluator,
+  ctx?: TaskExecutionContext,
+): Promise<unknown[]> {
+  const executeDoTasks = await getExecuteDoTasks();
+
+  const collection = await evaluateCollectionExpression(
+    taskDef.for.in,
+    state,
+    evaluateExpressions,
+  );
+
+  const items = toIterableSlice(collection);
+  const eachVar = taskDef.for.each ?? "item";
+  const atVar = taskDef.for.at ?? "index";
+  const results: unknown[] = [];
+
+  for (const item of items) {
+    if (ctx?.checkPause) await ctx.checkPause();
+
+    const iterState = state.clone();
+    iterState.clearOutput();
+
+    iterState.addData({
+      [eachVar]: item.value,
+      [atVar]: item.key,
+    });
+
+    if (taskDef.while !== undefined) {
+      const shouldContinue = await evaluateWhileCondition(
+        taskDef.while,
+        iterState,
+        evaluateExpressions,
+      );
+      if (!shouldContinue) break;
+    }
+
+    await executeDoTasks(
+      taskDef.do,
+      input,
+      iterState,
+      doc,
+      evaluateExpressions,
+      ctx,
+    );
+
+    results.push(iterState.output);
+  }
+
+  return results;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Collection Expression Evaluation
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates the `for.in` expression to obtain the collection.
+ * Expression is evaluated with null jq input and state variables,
+ * matching Go's `EvaluateString(for.In, nil, state)`.
+ */
+async function evaluateCollectionExpression(
+  expression: string,
+  state: WorkflowState,
+  evaluateExpressions: ExpressionEvaluator,
+): Promise<unknown> {
+  const rawExpr = expression.startsWith("${ ") && expression.endsWith(" }")
+    ? expression.slice(3, -2)
+    : expression;
+
+  const stateVars = state.getAsMap();
+  const results = await evaluateExpressions(
+    { __collection__: rawExpr },
+    null,
+    stateVars,
+  );
+
+  return results.__collection__;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Collection Normalization
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Normalizes the evaluated collection into an ordered list of
+ * key/value pairs. Mirrors Go's `toIterableSlice()`.
+ *
+ * - Array → [{key: 0, value: el}, ...]
+ * - Plain object → [{key: "k", value: v}, ...]
+ * - Integer N → [{key: 0, value: 0}, ..., {key: N-1, value: N-1}]
+ */
+function toIterableSlice(data: unknown): IterItem[] {
+  if (Array.isArray(data)) {
+    return data.map((value, index) => ({ key: index, value }));
+  }
+
+  if (typeof data === "number" && Number.isInteger(data) && data >= 0) {
+    return Array.from({ length: data }, (_, i) => ({ key: i, value: i }));
+  }
+
+  if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+    return Object.entries(data as Record<string, unknown>).map(
+      ([key, value]) => ({ key, value }),
+    );
+  }
+
+  const typeDesc = data === null ? "null" : typeof data;
+  throw new Error(
+    `for.in expression must evaluate to an array, object, or non-negative integer, ` +
+    `got ${typeDesc}: ${JSON.stringify(data)}`,
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// While Condition
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates the `while` condition against the current iteration state.
+ * Returns true to continue, false to stop. Non-boolean results are
+ * treated as false (matching Go's behavior).
+ */
+async function evaluateWhileCondition(
+  expression: string,
+  state: WorkflowState,
+  evaluateExpressions: ExpressionEvaluator,
+): Promise<boolean> {
+  const rawExpr = expression.startsWith("${ ") && expression.endsWith(" }")
+    ? expression.slice(3, -2)
+    : expression;
+
+  const stateVars = state.getAsMap();
+  const results = await evaluateExpressions(
+    { __while__: rawExpr },
+    null,
+    stateVars,
+  );
+
+  const result = results.__while__;
+  if (typeof result === "boolean") return result;
+  if (typeof result === "string") {
+    return result.toUpperCase() === "TRUE" || result === "1";
+  }
+  return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Placeholder Builder (for task-factory.ts registration)
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Placeholder builder for `for` tasks. The actual execution is handled
+ * by the do-executor via `executeForTask()` — this builder exists only
+ * to satisfy the TaskBuilder interface in the task factory.
+ */
+export class ForTaskPlaceholderBuilder 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(
+        `ForTaskPlaceholderBuilder.build() should never be called directly. ` +
+        `The executor handles 'for' tasks via executeForTask().`,
+      );
+    };
+  }
+
+  async shouldRun() {
+    return true;
+  }
+}
+
+export const FOR_TASK_KIND = "for" as const;

package/src/workflow-engine/tasks/fork.ts

@@ -0,0 +1,228 @@
+/**
+ * ForkTask executor — runs branches in parallel, collecting results
+ * into a map keyed by branch name (non-compete) or returning the
+ * first branch to complete (compete/race mode).
+ *
+ * Mirrors Go's `ForkTaskBuilder` in `task_builder_fork.go`. Key
+ * behaviors replicated here:
+ *
+ * - Branches validated at execution time (>= 1 required)
+ * - Parent state snapshot cloned once, then each branch clones from it
+ * - Each branch gets isolated state (clone + clearOutput)
+ * - Non-compete: Promise.all, output = { branchName: branchOutput }
+ * - Compete: first settlement wins, output = winner's raw output
+ * - Any non-cancellation error from any branch fails the fork
+ * - Parent state is never mutated by branch execution
+ *
+ * Cancellation of losing branches in compete mode is intentionally
+ * omitted to preserve kernel Temporal-agnosticism. Losing branches
+ * run to completion but their results are discarded. Go's cancellation
+ * via workflow.WithCancel also does not short-circuit in practice
+ * (documented in TestWorkflowFork_CompeteCancellationTiming).
+ */
+
+import type {
+  ForkTaskDef,
+  DoTaskDef,
+  WorkflowModel,
+  WorkflowState,
+  ExpressionEvaluator,
+  TaskExecutionContext,
+  TaskBuilder,
+  TaskDef,
+  TaskList,
+} from "../types.js";
+
+let _executeDoTasks: typeof import("../do-executor.js").executeDoTasks | null = null;
+
+async function getExecuteDoTasks() {
+  if (_executeDoTasks === null) {
+    const mod = await import("../do-executor.js");
+    _executeDoTasks = mod.executeDoTasks;
+  }
+  return _executeDoTasks;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Core Execution
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Executes a `fork` task — the parallel execution engine.
+ *
+ * Called directly by the do-executor's `runSingleTask()` when it
+ * encounters a task with `kind: "fork"`.
+ */
+export async function executeForkTask(
+  taskDef: ForkTaskDef,
+  input: unknown,
+  state: WorkflowState,
+  doc: WorkflowModel,
+  evaluateExpressions: ExpressionEvaluator,
+  ctx?: TaskExecutionContext,
+): Promise<unknown> {
+  const branches = taskDef.fork.branches;
+
+  if (branches.length === 0) {
+    throw new Error("Fork task requires at least one branch");
+  }
+
+  const executeDoTasks = await getExecuteDoTasks();
+  const childSnapshot = state.clone();
+  childSnapshot.clearOutput();
+
+  if (taskDef.fork.compete) {
+    return executeCompete(branches, input, childSnapshot, doc, evaluateExpressions, ctx, executeDoTasks);
+  }
+
+  return executeAllBranches(branches, input, childSnapshot, doc, evaluateExpressions, ctx, executeDoTasks);
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Non-Compete: All Branches (Promise.all)
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Runs all branches in parallel. Fails fast on the first error.
+ * Returns a map of { branchName: branchOutput }.
+ */
+async function executeAllBranches(
+  branches: TaskList,
+  input: unknown,
+  childSnapshot: WorkflowState,
+  doc: WorkflowModel,
+  evaluateExpressions: ExpressionEvaluator,
+  ctx: TaskExecutionContext | undefined,
+  executeDoTasks: typeof import("../do-executor.js").executeDoTasks,
+): Promise<Record<string, unknown>> {
+  const branchPromises = branches.map(async (branch) => {
+    const branchState = childSnapshot.clone();
+    branchState.clearOutput();
+
+    const branchTasks = normalizeBranchTasks(branch.key, branch.task);
+
+    await executeDoTasks(
+      branchTasks,
+      input,
+      branchState,
+      doc,
+      evaluateExpressions,
+      ctx,
+    );
+
+    return { name: branch.key, output: branchState.output };
+  });
+
+  const results = await Promise.all(branchPromises);
+
+  const output: Record<string, unknown> = {};
+  for (const result of results) {
+    output[result.name] = result.output;
+  }
+  return output;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Compete: First Settlement Wins (Race)
+// ─────────────────────────────────────────────────────────────────────
+
+interface RaceResult {
+  readonly output: unknown;
+}
+
+/**
+ * Races all branches. The first branch to resolve determines the
+ * fork output. The first branch to reject fails the fork.
+ *
+ * Losing branches continue running in the background but their
+ * results are discarded. Rejections from losing branches are
+ * silently caught to prevent unhandled promise rejection warnings.
+ */
+async function executeCompete(
+  branches: TaskList,
+  input: unknown,
+  childSnapshot: WorkflowState,
+  doc: WorkflowModel,
+  evaluateExpressions: ExpressionEvaluator,
+  ctx: TaskExecutionContext | undefined,
+  executeDoTasks: typeof import("../do-executor.js").executeDoTasks,
+): Promise<unknown> {
+  const branchPromises = branches.map(async (branch): Promise<RaceResult> => {
+    const branchState = childSnapshot.clone();
+    branchState.clearOutput();
+
+    const branchTasks = normalizeBranchTasks(branch.key, branch.task);
+
+    await executeDoTasks(
+      branchTasks,
+      input,
+      branchState,
+      doc,
+      evaluateExpressions,
+      ctx,
+    );
+
+    return { output: branchState.output };
+  });
+
+  // Attach no-op catch handlers to all promises so that rejections
+  // from losing branches don't surface as unhandled rejections.
+  // The actual error propagation happens through the race winner.
+  for (const p of branchPromises) {
+    p.catch(() => {});
+  }
+
+  const winner = await Promise.race(branchPromises);
+  return winner.output;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Branch Normalization
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Normalizes a branch's task definition into a TaskList suitable
+ * for executeDoTasks(). Branches parsed from YAML are typically
+ * DoTaskDefs (the branch contains a `do:` block), but a single
+ * leaf task is wrapped into a one-element task list.
+ *
+ * Mirrors Go's branch wrapping in ForkTaskBuilder.buildOrPostLoad().
+ */
+function normalizeBranchTasks(branchName: string, task: TaskDef): TaskList {
+  if (task.kind === "do") {
+    return (task as DoTaskDef).do;
+  }
+  return [{ key: branchName, task }];
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Placeholder Builder (for task-factory.ts registration)
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Placeholder builder for `fork` tasks. The actual execution is
+ * handled by the do-executor via `executeForkTask()` — this builder
+ * exists only to satisfy the TaskBuilder interface in the task factory.
+ */
+export class ForkTaskPlaceholderBuilder 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(
+        `ForkTaskPlaceholderBuilder.build() should never be called directly. ` +
+        `The executor handles 'fork' tasks via executeForkTask().`,
+      );
+    };
+  }
+
+  async shouldRun() {
+    return true;
+  }
+}

package/src/workflow-engine/tasks/human-input.ts

@@ -0,0 +1,147 @@
+/**
+ * Human input task executor — HITL approval gate.
+ *
+ * Pauses workflow execution until a human reviewer responds via signal.
+ * Supports configurable timeout with policies (fail, auto-approve, auto-deny).
+ *
+ * The kernel validates the config and delegates to `ctx.awaitHumanInput()`
+ * which is wired to the Temporal workflow layer's signal/timer selector.
+ *
+ * Outcome routing: when an outcome defines a `then` field (e.g.,
+ * `then: "gatherMore"`), the returned output includes a
+ * `__flow_directive__` that the do-executor uses to jump to the
+ * named task — the same mechanism used by switch and validate tasks.
+ *
+ * YAML shape (via loader reclassification from call: human_input):
+ *   - requireApproval:
+ *       call: human_input
+ *       with:
+ *         prompt: "Please review this deployment"
+ *         timeout: 300
+ *         on_timeout: approve
+ *         outcomes:
+ *           - name: approve
+ *           - name: deny
+ *           - name: revise
+ *             then: gatherMore
+ */
+
+import type {
+  HumanInputTaskDef,
+  HumanInputConfig,
+  WorkflowState,
+  TaskExecutionContext,
+  HumanInputResult,
+} from "../types.js";
+import { resolveEmbeddedExpressions } from "../resolve.js";
+import { isStrictExpr } from "../expression-utils.js";
+
+const SIGNAL_PREFIX = "human_input_";
+const DEFAULT_TIMEOUT_SECONDS = 0;
+const DEFAULT_ON_TIMEOUT = "fail" as const;
+
+/**
+ * Executes a human_input task. Called from `runSingleTask` in do-executor
+ * when the task kind is "human_input".
+ */
+export async function executeHumanInputTask(
+  taskDef: HumanInputTaskDef,
+  taskName: string,
+  state: WorkflowState,
+  ctx: TaskExecutionContext,
+): Promise<unknown> {
+  const config = taskDef.humanInput;
+  validateConfig(config, taskName);
+
+  const signalName = SIGNAL_PREFIX + taskName;
+  const timeoutSeconds = config.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+  const onTimeout = config.onTimeout ?? DEFAULT_ON_TIMEOUT;
+
+  const resolvedPrompt = await resolvePromptExpressions(
+    config.prompt, state, ctx,
+  );
+
+  const approvalRequestedAt = Date.now();
+
+  ctx.taskStatusAccumulator?.taskWaitingApproval(taskName);
+
+  if (ctx.emitEvents) {
+    await ctx.emitEvents([{
+      type: "approval_requested",
+      taskName,
+      occurredAt: new Date().toISOString(),
+      prompt: resolvedPrompt,
+      approvers: config.approvers ?? [],
+      timeoutSeconds,
+      outcomes: (config.outcomes ?? []).map((o) => ({
+        name: o.name,
+        label: o.label ?? "",
+      })),
+      formSchema: config.formSchema,
+    }]);
+  }
+
+  const result: HumanInputResult = await ctx.awaitHumanInput({
+    signalName,
+    timeoutSeconds,
+    onTimeout,
+  });
+
+  if (ctx.emitEvents) {
+    await ctx.emitEvents([{
+      type: "approval_resolved",
+      taskName,
+      occurredAt: new Date().toISOString(),
+      outcome: result.outcome,
+      resolvedBy: result.reviewer ?? "",
+      comment: "",
+      waitDurationMs: Date.now() - approvalRequestedAt,
+      autoResolved: result.auto_resolved ?? false,
+    }]);
+  }
+
+  state.addData({ [taskName]: result });
+
+  const selectedOutcome = config.outcomes?.find(o => o.name === result.outcome);
+  if (selectedOutcome?.then) {
+    return { ...result, __flow_directive__: selectedOutcome.then };
+  }
+
+  return result;
+}
+
+function validateConfig(config: HumanInputConfig, taskName: string): void {
+  if (!config.prompt) {
+    throw new Error(`human_input task '${taskName}': 'prompt' is required`);
+  }
+}
+
+/**
+ * Resolves `${ ... }` expressions in the prompt string against the
+ * current workflow state. Handles both strict (whole-value) and embedded
+ * (inline fragment) expression patterns.
+ */
+async function resolvePromptExpressions(
+  prompt: string,
+  state: WorkflowState,
+  ctx: TaskExecutionContext,
+): Promise<string> {
+  const stateVars = state.getAsMap();
+
+  // Strict expression: entire prompt is a single expression
+  if (isStrictExpr(prompt)) {
+    const expr = prompt.slice(3, -2);
+    const results = await ctx.evaluateExpressions(
+      { __prompt__: expr }, null, stateVars,
+    );
+    const resolved = results.__prompt__;
+    return typeof resolved === "string" ? resolved : JSON.stringify(resolved ?? "");
+  }
+
+  // Embedded expressions: inline `${ ... }` fragments within the prompt text
+  const wrapper = { prompt };
+  await resolveEmbeddedExpressions(
+    wrapper, null, stateVars, ctx.evaluateExpressions,
+  );
+  return wrapper.prompt;
+}