@stigmer/runner 3.0.1

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

@@ -0,0 +1,166 @@
+/**
+ * Listen task executor — waits for external events to arrive.
+ *
+ * The kernel validates and normalizes the listen configuration, then
+ * delegates to `ctx.listen()` which is wired to the Temporal workflow
+ * layer's listen-orchestrator. The kernel never imports Temporal types.
+ *
+ * Supports three consumption strategies:
+ * - `to.one`: single event (treated as "wait for all" with 1 event)
+ * - `to.all`: wait for ALL events to fire
+ * - `to.any`: wait for the FIRST event to fire
+ *
+ * Three Temporal transport types (Stigmer extension of CNCF DSL):
+ * - `type: "signal"` — blocking; receives data via Temporal signal channel
+ * - `type: "query"`  — non-blocking; registers a read-only query handler
+ *   that returns computed data (does NOT count toward all/any completion)
+ * - `type: "update"` — blocking; registers a bidirectional update handler
+ *   with validation (counts toward all/any completion like signals)
+ *
+ * YAML shape:
+ *   - waitForApproval:
+ *       listen:
+ *         to:
+ *           one:
+ *             with:
+ *               id: approval_signal
+ *               type: signal
+ */
+
+import type {
+  ListenTaskDef,
+  ListenConfig,
+  EventFilter,
+  ListenExecutionConfig,
+  ListenEventDef,
+  WorkflowState,
+  TaskExecutionContext,
+} from "../types.js";
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const SUPPORTED_EVENT_TYPES = ["signal", "query", "update"];
+
+/**
+ * Executes a listen task. Called from `runSingleTask` in do-executor
+ * when the task kind is "listen".
+ */
+export async function executeListenTask(
+  taskDef: ListenTaskDef,
+  taskName: string,
+  state: WorkflowState,
+  ctx: TaskExecutionContext,
+): Promise<unknown> {
+  const config = normalizeListenConfig(taskDef.listen, taskName);
+  const result = await ctx.listen(config);
+
+  if (result !== undefined && result !== null) {
+    state.addData({ [taskName]: result });
+  }
+
+  return result;
+}
+
+/**
+ * Validates and normalizes the raw ListenConfig into a
+ * ListenExecutionConfig suitable for the workflow orchestrator.
+ */
+function normalizeListenConfig(
+  listen: ListenConfig,
+  taskName: string,
+): ListenExecutionConfig {
+  const { events, mode } = extractEvents(listen, taskName);
+  const timeoutMs = extractTimeout(listen, taskName);
+
+  return { events, mode, timeoutMs };
+}
+
+function extractEvents(
+  listen: ListenConfig,
+  taskName: string,
+): { events: ListenEventDef[]; mode: "all" | "any" } {
+  const to = listen.to;
+  if (!to) {
+    throw new Error(`Listen task '${taskName}': 'to' configuration is required`);
+  }
+
+  let rawFilters: EventFilter[];
+  let mode: "all" | "any";
+
+  if (to.one) {
+    rawFilters = [to.one];
+    mode = "all";
+  } else if (to.all && to.all.length > 0) {
+    rawFilters = to.all;
+    mode = "all";
+  } else if (to.any && to.any.length > 0) {
+    rawFilters = to.any;
+    mode = "any";
+  } else {
+    throw new Error(
+      `Listen task '${taskName}': at least one event must be defined in 'to.one', 'to.all', or 'to.any'`,
+    );
+  }
+
+  const events = rawFilters.map((filter, i) => validateEventFilter(filter, taskName, i));
+  return { events, mode };
+}
+
+function validateEventFilter(
+  filter: EventFilter,
+  taskName: string,
+  index: number,
+): ListenEventDef {
+  const w = filter.with as Record<string, unknown> | undefined;
+  if (!w) {
+    throw new Error(
+      `Listen task '${taskName}': event[${index}] must have a 'with' configuration`,
+    );
+  }
+
+  const id = w.id as string | undefined;
+  if (!id) {
+    throw new Error(
+      `Listen task '${taskName}': event[${index}].with.id is required`,
+    );
+  }
+
+  const type = w.type as string | undefined;
+  if (!type) {
+    throw new Error(
+      `Listen task '${taskName}': event[${index}].with.type is required`,
+    );
+  }
+
+  if (!SUPPORTED_EVENT_TYPES.includes(type)) {
+    throw new Error(
+      `Listen task '${taskName}': event[${index}].with.type '${type}' is not supported. ` +
+      `Supported types: ${SUPPORTED_EVENT_TYPES.join(", ")}`,
+    );
+  }
+
+  const acceptIf = w.acceptIf as string | undefined;
+  const data = w.data as unknown | undefined;
+
+  return { id, type, acceptIf, data };
+}
+
+function extractTimeout(listen: ListenConfig, _taskName: string): number {
+  const metadata = (listen as unknown as { metadata?: Record<string, unknown> }).metadata;
+  if (!metadata?.timeout) return DEFAULT_TIMEOUT_MS;
+
+  const timeoutStr = metadata.timeout;
+  if (typeof timeoutStr === "number") return timeoutStr * 1000;
+  if (typeof timeoutStr !== "string") return DEFAULT_TIMEOUT_MS;
+
+  const match = timeoutStr.match(/^(\d+)(ms|s|m|h)$/);
+  if (!match) return DEFAULT_TIMEOUT_MS;
+
+  const value = parseInt(match[1], 10);
+  switch (match[2]) {
+    case "ms": return value;
+    case "s": return value * 1_000;
+    case "m": return value * 60_000;
+    case "h": return value * 3_600_000;
+    default: return DEFAULT_TIMEOUT_MS;
+  }
+}

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

@@ -0,0 +1,81 @@
+/**
+ * RaiseTask builder — throws a typed WorkflowError from a YAML
+ * error definition. Supports expression evaluation in `title`
+ * and `detail` fields via jq.
+ *
+ * Mirrors Go's `RaiseTaskBuilder` in `task_builder_raise.go`.
+ * The `raise` task is the deliberate error-throwing companion
+ * to `try/catch` — it lets workflow authors produce structured
+ * errors that catch blocks can filter and inspect.
+ */
+
+import type {
+  RaiseTaskDef,
+  TaskBuilder,
+  TaskExecutorFn,
+} from "../types.js";
+import { WorkflowError } from "../errors.js";
+
+export class RaiseTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: RaiseTaskDef;
+
+  constructor(taskName: string, taskDef: RaiseTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build(): TaskExecutorFn {
+    return async (_input, state, ctx) => {
+      const errorDef = this.taskDef.raise.error;
+
+      let title = errorDef.title ?? "";
+      let detail = errorDef.detail ?? "";
+
+      const expressions: Record<string, string> = {};
+
+      if (isExpression(title)) {
+        expressions.__raise_title__ = unwrapExpression(title);
+      }
+      if (isExpression(detail)) {
+        expressions.__raise_detail__ = unwrapExpression(detail);
+      }
+
+      if (Object.keys(expressions).length > 0) {
+        const stateVars = state.getAsMap();
+        const results = await ctx.evaluateExpressions(
+          expressions,
+          null,
+          stateVars,
+        );
+
+        if ("__raise_title__" in results) {
+          title = String(results.__raise_title__ ?? "");
+        }
+        if ("__raise_detail__" in results) {
+          detail = String(results.__raise_detail__ ?? "");
+        }
+      }
+
+      throw new WorkflowError({
+        type: errorDef.type,
+        status: errorDef.status,
+        title,
+        detail,
+        instance: errorDef.instance,
+      });
+    };
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+}
+
+function isExpression(value: string): boolean {
+  return value.startsWith("${ ") && value.endsWith(" }");
+}
+
+function unwrapExpression(value: string): string {
+  return value.slice(3, -2);
+}

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

@@ -0,0 +1,142 @@
+/**
+ * Run task builder — executes inline scripts, shell commands, or child workflows.
+ *
+ * Three execution modes:
+ * - `run.script`: Inline JS/Python executed via activity (temp file + child_process)
+ * - `run.shell`: Shell command executed via activity (child_process.exec)
+ * - `run.workflow`: Child Temporal workflow (await or fire-and-forget)
+ *
+ * The kernel validates configuration and delegates to `ctx.runCommand`
+ * (for script/shell) or `ctx.runWorkflow` (for child workflows).
+ *
+ * YAML shapes:
+ *   - runScript:
+ *       run:
+ *         script:
+ *           language: js
+ *           code: "console.log('hello')"
+ *
+ *   - runShell:
+ *       run:
+ *         shell:
+ *           command: echo
+ *           arguments: { msg: "hello" }
+ *
+ *   - runChild:
+ *       run:
+ *         workflow:
+ *           name: child-workflow
+ *           namespace: default
+ *           version: '1.0.0'
+ */
+
+import type {
+  TaskBuilder,
+  TaskDef,
+  TaskExecutorFn,
+  RunTaskDef,
+  RunConfig,
+  WorkflowState,
+  TaskExecutionContext,
+} from "../types.js";
+
+const SUPPORTED_LANGUAGES = ["js", "python"];
+
+export class RunTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: TaskDef;
+
+  constructor(taskName: string, taskDef: RunTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build(): TaskExecutorFn {
+    const runDef = this.taskDef as RunTaskDef;
+    const config = runDef.run;
+    const taskName = this.taskName;
+
+    validateRunConfig(config, taskName);
+
+    return async (_input: unknown, state: WorkflowState, ctx: TaskExecutionContext) => {
+      let result: unknown;
+
+      if (config.script) {
+        result = await ctx.runCommand({
+          mode: "script",
+          language: config.script.language,
+          code: config.script.code,
+          arguments: config.script.arguments,
+          environment: config.script.environment,
+          runtimeEnv: state.env as Record<string, unknown>,
+        });
+      } else if (config.shell) {
+        result = await ctx.runCommand({
+          mode: "shell",
+          command: config.shell.command,
+          arguments: config.shell.arguments,
+          environment: config.shell.environment,
+          runtimeEnv: state.env as Record<string, unknown>,
+        });
+      } else if (config.workflow) {
+        result = await ctx.runWorkflow({
+          name: config.workflow.name,
+          input: config.workflow.input,
+          await: true,
+        });
+      }
+
+      if (result !== undefined) {
+        state.addData({ [taskName]: result });
+      }
+
+      return result;
+    };
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+}
+
+function validateRunConfig(config: RunConfig, taskName: string): void {
+  const modes = [config.script, config.shell, config.workflow].filter(Boolean);
+
+  if (modes.length === 0) {
+    throw new Error(
+      `Run task '${taskName}': exactly one of 'script', 'shell', or 'workflow' must be defined`,
+    );
+  }
+  if (modes.length > 1) {
+    throw new Error(
+      `Run task '${taskName}': only one of 'script', 'shell', or 'workflow' may be defined`,
+    );
+  }
+
+  if (config.script) {
+    if (!config.script.language) {
+      throw new Error(`Run task '${taskName}': script.language is required`);
+    }
+    if (!SUPPORTED_LANGUAGES.includes(config.script.language)) {
+      throw new Error(
+        `Run task '${taskName}': unsupported script language '${config.script.language}'. ` +
+        `Supported: ${SUPPORTED_LANGUAGES.join(", ")}`,
+      );
+    }
+    if (!config.script.code) {
+      throw new Error(`Run task '${taskName}': script.code is required`);
+    }
+  }
+
+  if (config.shell) {
+    if (!config.shell.command) {
+      throw new Error(`Run task '${taskName}': shell.command is required`);
+    }
+  }
+
+  if (config.workflow) {
+    if (!config.workflow.name) {
+      throw new Error(`Run task '${taskName}': workflow.name is required`);
+    }
+  }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * SetTask builder — evaluates expressions in the `set` object and
+ * merges results into state.data. The simplest task type: pure state
+ * mutation with no I/O.
+ *
+ * Mirrors Go's `task_builder_set.go`.
+ */
+
+import type {
+  SetTaskDef,
+  TaskBuilder,
+  TaskExecutorFn,
+} from "../types.js";
+import { collectExpressions, substituteResults } from "../resolve.js";
+import { deepClone } from "../clone.js";
+
+export class SetTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: SetTaskDef;
+
+  constructor(taskName: string, taskDef: SetTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build(): TaskExecutorFn {
+    return async (_input, state, ctx) => {
+      const setObject = deepClone(this.taskDef.set);
+
+      const stateVars = state.getAsMap();
+      const result = await ctx.evaluateExpressions(
+        collectExpressions(setObject),
+        null,
+        stateVars,
+      );
+
+      const evaluated = substituteResults(setObject, result);
+
+      state.addData(evaluated as Record<string, unknown>);
+      return evaluated;
+    };
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * SwitchTask builder — evaluates `when` conditions sequentially and
+ * returns the matching case's `then` flow directive. A switch with
+ * no `when` clause acts as the default case.
+ *
+ * The switch task does not produce output — it only controls flow
+ * by setting the `then` directive on the task base, which the
+ * DoTask executor reads to determine the next task.
+ *
+ * Mirrors Go's `task_builder_switch.go`.
+ */
+
+import type {
+  SwitchTaskDef,
+  TaskBuilder,
+  TaskExecutorFn,
+  FlowDirective,
+} from "../types.js";
+import { isTermination } from "../types.js";
+
+export class SwitchTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: SwitchTaskDef;
+
+  constructor(taskName: string, taskDef: SwitchTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+    this.validateNoDuplicateDefaults();
+  }
+
+  build(): TaskExecutorFn {
+    return async (_input, state, ctx) => {
+      const stateVars = state.getAsMap();
+
+      for (const switchCase of this.taskDef.switch) {
+        if (switchCase.when === undefined) {
+          return { __flow_directive__: switchCase.then } as unknown;
+        }
+
+        const whenExpr = switchCase.when;
+        const result = await ctx.evaluateExpressions(
+          { condition: whenExpr.startsWith("${ ") ? whenExpr.slice(3, -2) : whenExpr },
+          null,
+          stateVars,
+        );
+
+        const conditionResult = result.condition;
+        if (isTruthy(conditionResult)) {
+          if (isTermination(switchCase.then)) {
+            return { __flow_directive__: switchCase.then } as unknown;
+          }
+          return { __flow_directive__: switchCase.then } as unknown;
+        }
+      }
+
+      return null;
+    };
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+
+  private validateNoDuplicateDefaults(): void {
+    let defaultCount = 0;
+    for (const switchCase of this.taskDef.switch) {
+      if (switchCase.when === undefined) {
+        defaultCount++;
+      }
+    }
+    if (defaultCount > 1) {
+      throw new Error(
+        `Switch task '${this.taskName}' has ${defaultCount} default cases (no 'when'). At most one is allowed.`,
+      );
+    }
+  }
+}
+
+/**
+ * Extracts the flow directive from a switch task's output.
+ * Returns undefined if the output doesn't contain a directive.
+ */
+export function extractFlowDirective(
+  output: unknown,
+): FlowDirective | undefined {
+  if (
+    output !== null &&
+    typeof output === "object" &&
+    "__flow_directive__" in (output as Record<string, unknown>)
+  ) {
+    return (output as Record<string, unknown>).__flow_directive__ as FlowDirective;
+  }
+  return undefined;
+}
+
+function isTruthy(value: unknown): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    return value.toUpperCase() === "TRUE" || value === "1";
+  }
+  return false;
+}