@stigmer/runner 3.2.1 → 3.2.3

package/src/workflow-engine/__tests__/tasks/call-function.test.ts

@@ -202,4 +202,98 @@ describe("CallFunctionTaskBuilder", () => {
     const calledMeta = mockCallFunction.mock.calls[0][3];
     expect(calledMeta.workflowExecutionId).toBeUndefined();
   });
+
+  // Deferred-code fields (upstream #7 regression): rule/transform
+  // expressions are jq CODE the activity evaluates against its own data.
+  // The config resolver must never pre-evaluate them — the pre-fix
+  // behavior substituted the evaluated boolean back into the config and
+  // crashed the validate activity with `expr.includes is not a function`.
+  describe("deferred expression fields", () => {
+    it("passes validate rules[].expression through unresolved while input and message interpolate", async () => {
+      mockCallFunction.mockResolvedValue({ valid: true, errors: [] });
+
+      const taskDef: CallFunctionTaskDef = {
+        kind: "call:function",
+        call: "validate",
+        with: {
+          input: "${ $context.total_order }",
+          rules: [
+            {
+              name: "total_is_positive",
+              expression: "${ .total > 0 }",
+              message: "Total ${ $context.total_order.currency } must be positive",
+            },
+          ],
+          on_fail: "VALIDATION_FAIL_RAISE",
+        },
+      };
+
+      const builder = new CallFunctionTaskBuilder("check_order", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      state.context = { total_order: { total: 150, currency: "USD" } };
+
+      await executor(null, state, makeCtx());
+
+      const calledConfig = mockCallFunction.mock.calls[0][1];
+      // Data fields resolve...
+      expect(calledConfig.input).toEqual({ total: 150, currency: "USD" });
+      expect(calledConfig.rules[0].message).toBe("Total USD must be positive");
+      // ...the rule predicate does NOT — it stays deferred code.
+      expect(calledConfig.rules[0].expression).toBe("${ .total > 0 }");
+    });
+
+    it("passes a ${ }-wrapped transform expression through unresolved", async () => {
+      mockCallFunction.mockResolvedValue({ total: 150 });
+
+      const taskDef: CallFunctionTaskDef = {
+        kind: "call:function",
+        call: "transform",
+        with: {
+          engine: "TRANSFORM_ENGINE_JQ",
+          expression: "${ { total: .qty } }",
+          input: "${ $context.order }",
+        },
+      };
+
+      const builder = new CallFunctionTaskBuilder("total_order", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      state.context = { order: { qty: 3 } };
+
+      await executor(null, state, makeCtx());
+
+      const calledConfig = mockCallFunction.mock.calls[0][1];
+      expect(calledConfig.input).toEqual({ qty: 3 });
+      expect(calledConfig.expression).toBe("${ { total: .qty } }");
+    });
+
+    it("does not mutate the original task definition across invocations", async () => {
+      mockCallFunction.mockResolvedValue({ valid: true, errors: [] });
+
+      const withConfig = {
+        input: "${ $context.order }",
+        rules: [{ name: "r", expression: "${ .total > 0 }" }],
+      };
+      const taskDef: CallFunctionTaskDef = {
+        kind: "call:function",
+        call: "validate",
+        with: withConfig,
+      };
+
+      const builder = new CallFunctionTaskBuilder("check", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      state.context = { order: { total: 1 } };
+
+      await executor(null, state, makeCtx());
+      await executor(null, state, makeCtx());
+
+      // Retry-safety: the shared definition object stays pristine.
+      expect(withConfig.input).toBe("${ $context.order }");
+      expect(withConfig.rules[0].expression).toBe("${ .total > 0 }");
+      const secondCall = mockCallFunction.mock.calls[1][1];
+      expect(secondCall.rules[0].expression).toBe("${ .total > 0 }");
+    });
+  });
 });

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

@@ -317,10 +317,50 @@ describe("executeHumanInputTask", () => {
       expect(resolved.taskName).toBe("gate");
       expect(resolved.outcome).toBe("reject");
       expect(resolved.resolvedBy).toBe("carol");
+      expect(resolved.resolvedByActor).toBeUndefined();
       expect(resolved.autoResolved).toBe(false);
       expect(resolved.waitDurationMs).toBeGreaterThanOrEqual(0);
     });
 
+    it("carries the reviewer_actor display snapshot into approval_resolved and the task output", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+      const reviewerActor = {
+        id: "ida_01abc",
+        display_name: "Ada Lovelace",
+        email: "ada@example.com",
+        avatar: "https://example.com/ada.png",
+      };
+      const awaitFn: AwaitHumanInputFn = async () => ({
+        outcome: "approve",
+        reviewer: "ida_01abc",
+        reviewer_actor: reviewerActor,
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Confirm?" },
+      };
+
+      const state = createState();
+      await executeHumanInputTask(taskDef, "gate", state, makeCtx(awaitFn, emitFn));
+
+      const resolved = emitted[1][0];
+      if (resolved.type !== "approval_resolved") throw new Error("unexpected");
+      expect(resolved.resolvedBy).toBe("ida_01abc");
+      expect(resolved.resolvedByActor).toEqual(reviewerActor);
+
+      // The whole signal payload IS the task output — the actor lands there
+      // for downstream tasks (e.g. notification templates) without copying.
+      expect(state.data.gate).toEqual({
+        outcome: "approve",
+        reviewer: "ida_01abc",
+        reviewer_actor: reviewerActor,
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+    });
+
     it("does not error when emitEvents is undefined (backward compat)", async () => {
       const awaitFn: AwaitHumanInputFn = async () => ({ outcome: "approve" });
 

package/src/workflow-engine/do-executor.ts

@@ -42,6 +42,39 @@ import { truncatePayload } from "./task-status-accumulator.js";
 import { extractRootErrorMessage, extractStructuredError } from "./error-utils.js";
 import type { RecoveryContext } from "./recovery.js";
 
+/**
+ * Deterministic-version gate id for the task_started emission reorder
+ * (input resolution moved ahead of the event so it can carry
+ * `input_summary`). Pre-change histories replay the old order — emit
+ * first, resolve second — via `TaskExecutionContext.isPatched`.
+ */
+export const TASK_STARTED_INPUT_SUMMARY_PATCH = "task-started-input-summary";
+
+/**
+ * Truncation budget for event I/O summaries. Deliberately far below the
+ * 64KB snapshot cap: events are the live-stream preview source and the
+ * proto documents them as "truncated to prevent event bloat" — the full
+ * I/O lives on `status.tasks[]`.
+ */
+const EVENT_SUMMARY_MAX_BYTES = 8_192;
+
+/**
+ * Projects a task I/O value into the shape an event summary Struct can
+ * carry: truncated to the event budget, objects only (mirroring the
+ * snapshot path's `toJsonObject` semantics — proto Struct fields cannot
+ * carry scalars or arrays, and `status.tasks[].input/output` share the
+ * same limitation). Oversize values come back as `truncatePayload`'s
+ * `{_truncated, _preview}` marker object, which IS carried.
+ */
+function toEventSummary(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || value === undefined) return undefined;
+  const truncated = truncatePayload(value, EVENT_SUMMARY_MAX_BYTES);
+  if (truncated === null || typeof truncated !== "object" || Array.isArray(truncated)) {
+    return undefined;
+  }
+  return truncated as Record<string, unknown>;
+}
+
 /**
  * Returns the task kind string used for event emission. For call:function
  * tasks, appends the specific function name (e.g., "call:function:llm")
@@ -156,21 +189,42 @@ export async function executeDoTasks(
     const kind = eventTaskKind(entry);
     effectiveCtx.taskStatusAccumulator?.taskStarted(entry.key, kind);
     const attemptNumber = effectiveCtx.taskStatusAccumulator?.getAttempt(entry.key) ?? 1;
-    if (effectiveCtx.emitEvents) {
+
+    const emitTaskStarted = async (
+      inputSummary?: Record<string, unknown>,
+    ): Promise<void> => {
+      if (!effectiveCtx.emitEvents) return;
       await effectiveCtx.emitEvents([{
         type: "task_started",
         taskName: entry.key,
         occurredAt: new Date().toISOString(),
         taskKind: kind,
         attemptNumber,
+        inputSummary,
       }]);
+    };
+
+    // Emission-order gate: carrying `input_summary` on task_started
+    // requires resolving the input BEFORE emitting, which reorders two
+    // local-activity commands — a non-deterministic change for in-flight
+    // histories (a gated or waiting task can be parked across a deploy).
+    // Pre-change histories replay the old emit-then-resolve order.
+    const emitStartedAfterResolve =
+      effectiveCtx.isPatched?.(TASK_STARTED_INPUT_SUMMARY_PATCH) ?? true;
+    if (!emitStartedAfterResolve) {
+      await emitTaskStarted();
     }
+    let startedEmitted = !emitStartedAfterResolve;
 
     const taskStartMs = Date.now();
     let taskOutput: unknown;
     try {
       const effectiveInput = await resolveTaskInput(entry, input, state, effectiveCtx);
       effectiveCtx.taskStatusAccumulator?.taskStartedWithInput(entry.key, kind, truncatePayload(effectiveInput));
+      if (emitStartedAfterResolve) {
+        await emitTaskStarted(toEventSummary(effectiveInput));
+        startedEmitted = true;
+      }
       taskOutput = await runSingleTask(entry, effectiveInput, state, doc, effectiveCtx);
     } catch (taskErr) {
       const taskDurationMs = Date.now() - taskStartMs;
@@ -190,6 +244,12 @@ export async function executeDoTasks(
         });
       }
       if (effectiveCtx.emitEvents) {
+        // Input resolution failed before the reordered task_started could
+        // fire — emit it now so consumers always see the started→failed pair.
+        if (!startedEmitted) {
+          await emitTaskStarted();
+          startedEmitted = true;
+        }
         await effectiveCtx.emitEvents([{
           type: "task_failed",
           taskName: entry.key,
@@ -239,6 +299,10 @@ export async function executeDoTasks(
         durationMs: taskDurationMs,
         costMicros: costInfo.costMicros,
         tokensUsed: costInfo.inputTokens + costInfo.outputTokens,
+        // The live-stream preview source for task cards: post-promotion
+        // output (the artifact-promoted form is what downstream sees),
+        // truncated to the event budget. Full output rides the snapshot.
+        outputSummary: toEventSummary(promotedOutput),
       }];
       for (const evt of promotionEvents) {
         events.push(evt as unknown as (typeof events)[number]);

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

@@ -17,6 +17,80 @@ import type {
 } from "../types.js";
 import { resolveConfigExpressions } from "../resolve.js";
 
+/**
+ * Detaches deferred-code fields from a call-function config before
+ * expression resolution and returns a restorer that puts the originals
+ * back afterwards.
+ *
+ * Some config fields carry jq CODE that the activity evaluates later
+ * against its own input — not data to interpolate at config time:
+ *
+ * - `transform.expression` — evaluated by `transformAction` against the
+ *   transform's `input`.
+ * - `validate.rules[].expression` — evaluated by `validateAction` per
+ *   rule against the validated data.
+ *
+ * Without the detach, a `${ }`-wrapped predicate is pre-evaluated here
+ * against the WRONG input and its non-string RESULT is substituted back
+ * into the config; the activity then tries to evaluate that result as jq
+ * (the `expr.includes is not a function` crash class). All other fields
+ * — including `rules[].message` and the llm/eval prompt fields — are
+ * data and continue to interpolate normally. The original config object
+ * is never mutated (shared across retries).
+ */
+function detachDeferredCode(
+  callType: string,
+  config: Record<string, unknown>,
+): {
+  readonly config: Record<string, unknown>;
+  readonly restore: (resolved: Record<string, unknown>) => void;
+} {
+  if (callType === "transform" && "expression" in config) {
+    const { expression, ...rest } = config;
+    return {
+      config: rest,
+      restore: (resolved) => {
+        resolved.expression = expression;
+      },
+    };
+  }
+
+  if (callType === "validate" && Array.isArray(config.rules)) {
+    const originalRules = config.rules as readonly unknown[];
+    const strippedRules = originalRules.map((rule) => {
+      if (isPlainObject(rule) && "expression" in rule) {
+        const { expression: _deferred, ...rest } = rule;
+        return rest;
+      }
+      return rule;
+    });
+    return {
+      config: { ...config, rules: strippedRules },
+      restore: (resolved) => {
+        const resolvedRules = resolved.rules;
+        if (!Array.isArray(resolvedRules)) return;
+        for (let i = 0; i < resolvedRules.length; i++) {
+          const original = originalRules[i];
+          const target = resolvedRules[i];
+          if (
+            isPlainObject(original) &&
+            isPlainObject(target) &&
+            "expression" in original
+          ) {
+            target.expression = original.expression;
+          }
+        }
+      },
+    };
+  }
+
+  return { config, restore: () => {} };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 interface LlmActivityResult {
   readonly result: unknown;
   readonly model: string;
@@ -64,15 +138,22 @@ export class CallFunctionTaskBuilder implements TaskBuilder {
   build(): TaskExecutorFn {
     return async (input, state, ctx) => {
       const withConfig = this.taskDef.with ?? {};
+      const callType = this.taskDef.call;
 
-      const resolved = await resolveConfigExpressions(
+      // Deferred-code fields (transform/validate expressions) must reach
+      // the activity as unresolved jq strings — see detachDeferredCode.
+      const deferred = detachDeferredCode(
+        callType,
         withConfig as Record<string, unknown>,
+      );
+
+      const resolved = await resolveConfigExpressions(
+        deferred.config,
         input,
         state,
         ctx.evaluateExpressions,
       );
-
-      const callType = this.taskDef.call;
+      deferred.restore(resolved);
       if ((callType === "transform" || callType === "validate") &&
           !("input" in resolved) || resolved.input === undefined) {
         resolved.input = input;

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

@@ -109,6 +109,7 @@ export async function executeHumanInputTask(
       occurredAt: new Date().toISOString(),
       outcome: result.outcome,
       resolvedBy: result.reviewer ?? "",
+      resolvedByActor: result.reviewer_actor,
       comment: "",
       waitDurationMs: Date.now() - approvalRequestedAt,
       autoResolved: result.auto_resolved ?? false,

package/src/workflow-engine/types.ts

@@ -449,6 +449,18 @@ export interface TaskExecutionContext {
    */
   readonly checkPause?: () => Promise<void>;
 
+  /**
+   * Deterministic version gate for engine behavior changes that alter
+   * the workflow's command sequence — Temporal `patched()` semantics:
+   * `true` for new executions (recording a marker) and for replays whose
+   * history carries the marker; `false` when replaying pre-change
+   * histories, which must re-execute the old command order. Wired to
+   * Temporal's `patched()` in the workflow function; the kernel stays
+   * Temporal-agnostic and treats an absent gate as "change active"
+   * (tests and the minimal context never replay old histories).
+   */
+  readonly isPatched?: (changeId: string) => boolean;
+
   /**
    * Accumulates per-task status entries throughout the workflow run.
    * Passed to the emit activity on every event batch so the server
@@ -551,13 +563,33 @@ export interface HumanInputExecutionConfig {
 
 export interface HumanInputResult {
   readonly outcome: string;
+  /** Canonical reviewer identity (identity-account ID). Empty/absent when unattributed. */
   readonly reviewer?: string;
+  /**
+   * Display snapshot of the reviewer, stamped server-side by the control
+   * plane at decision time. Rides the signal opaquely into the task output
+   * (for downstream tasks, e.g. notifications) and the approval_resolved
+   * event (for UIs). Absent when no attribution exists — never synthesized.
+   */
+  readonly reviewer_actor?: HumanInputReviewerActor;
   readonly responded_at?: string;
   readonly form_data?: Record<string, unknown>;
   readonly auto_resolved?: boolean;
   readonly reason?: string;
 }
 
+/** Write-time snapshot of the reviewer's display identity. */
+export interface HumanInputReviewerActor {
+  /** Canonical identity (matches HumanInputResult.reviewer). */
+  readonly id: string;
+  /** Human-readable name; empty when unknown. */
+  readonly display_name?: string;
+  /** Email address; empty when unknown. */
+  readonly email?: string;
+  /** Avatar URL; empty when unknown. */
+  readonly avatar?: string;
+}
+
 export interface HumanInputConfig {
   readonly prompt: string;
   readonly outcomes?: HumanInputOutcome[];
@@ -764,6 +796,14 @@ export interface TaskStartedEvent extends EventBase {
   readonly type: "task_started";
   readonly taskKind: string;
   readonly attemptNumber: number;
+  /**
+   * Truncated resolved task input (proto `TaskStartedPayload.input_summary`).
+   * The live-stream preview source for task cards — the FULL input lives on
+   * the status snapshot. Only present when the input is a plain object
+   * (proto Struct constraint, mirroring `status.tasks[].input`) and when
+   * emission happens after input resolution (the patched()-gated path).
+   */
+  readonly inputSummary?: Record<string, unknown>;
 }
 
 export interface TaskCompletedEvent extends EventBase {
@@ -772,6 +812,13 @@ export interface TaskCompletedEvent extends EventBase {
   readonly durationMs: number;
   readonly costMicros: number;
   readonly tokensUsed: number;
+  /**
+   * Truncated task output (proto `TaskCompletedPayload.output_summary`).
+   * The live-stream preview source for task cards — the FULL output lives
+   * on the status snapshot. Only present when the output is a plain object
+   * (proto Struct constraint, mirroring `status.tasks[].output`).
+   */
+  readonly outputSummary?: Record<string, unknown>;
 }
 
 export interface TaskFailedEvent extends EventBase {
@@ -816,7 +863,10 @@ export interface ApprovalRequestedEvent extends EventBase {
 export interface ApprovalResolvedEvent extends EventBase {
   readonly type: "approval_resolved";
   readonly outcome: string;
+  /** Canonical reviewer identity. Empty when unattributed. */
   readonly resolvedBy: string;
+  /** Display snapshot of the reviewer from the signal payload, if stamped. */
+  readonly resolvedByActor?: HumanInputReviewerActor;
   readonly comment: string;
   readonly waitDurationMs: number;
   readonly autoResolved: boolean;

package/src/workflows/__tests__/execute-serverless-workflow.test.ts

@@ -33,6 +33,7 @@ vi.mock("@temporalio/workflow", () => ({
   setHandler: vi.fn(),
   condition: vi.fn(),
   sleep: vi.fn(),
+  patched: vi.fn(() => true),
   workflowInfo: vi.fn(() => ({ workflowId: "test-wf-id" })),
   ApplicationFailure: class ApplicationFailure extends Error {
     constructor(msg: string) { super(msg); }

package/src/workflows/engine-core.ts

@@ -13,7 +13,7 @@
  * type-only imports, and pure JS/TS logic.
  */
 
-import { proxyLocalActivities, proxyActivities, log, workflowInfo, sleep } from "@temporalio/workflow";
+import { proxyLocalActivities, proxyActivities, log, patched, workflowInfo, sleep } from "@temporalio/workflow";
 import { ApplicationFailure, CancelledFailure, ActivityFailure } from "@temporalio/workflow";
 import { recordExecutionStartMetric, recordExecutionEndMetric } from "./metrics-sink.js";
 
@@ -200,6 +200,10 @@ export async function runWorkflowEngine(
     checkPause: options?.checkPause,
     emitEvents,
     taskStatusAccumulator,
+    // Deterministic version gate for engine command-order changes (the
+    // kernel never imports Temporal APIs — it receives patched() as an
+    // opaque callback, like every other capability on this context).
+    isPatched: (changeId: string) => patched(changeId),
     sleep: async (durationMs: number) => {
       try {
         await sleep(durationMs);

package/src/workflows/human-input-orchestrator.ts

@@ -8,7 +8,8 @@
  * - "approve": returns auto-approved output
  * - "deny": returns auto-denied output
  *
- * Signal payload shape: { outcome, form_data?, reviewer, responded_at }
+ * Signal payload shape:
+ * { outcome, form_data?, reviewer, reviewer_actor?, responded_at }
  *
  * TEMPORAL SANDBOX: This file runs inside the deterministic workflow isolate.
  */