@stigmer/runner 3.1.9 → 3.1.11

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

@@ -1,6 +1,8 @@
 import { describe, it, expect, vi } from "vitest";
 import { executeHumanInputTask } from "../../tasks/human-input.js";
 import { createState } from "../../state.js";
+import { evaluateExpressionBatch } from "../../expression.js";
+import { TaskStatusAccumulator } from "../../task-status-accumulator.js";
 import type {
   HumanInputTaskDef,
   TaskExecutionContext,
@@ -8,14 +10,28 @@ import type {
   HumanInputResult,
   AwaitHumanInputFn,
   EmitEventsFn,
+  ExpressionEvaluator,
+  PromoteTaskOutputFn,
   WorkflowEventDescriptor,
 } from "../../types.js";
 
 const notAvailable = () => { throw new Error("not available in test"); };
 
-function makeCtx(awaitFn?: AwaitHumanInputFn, emitFn?: EmitEventsFn): TaskExecutionContext {
+interface CtxOptions {
+  readonly awaitFn?: AwaitHumanInputFn;
+  readonly emitFn?: EmitEventsFn;
+  readonly evaluateExpressions?: ExpressionEvaluator;
+  readonly promoteTaskOutput?: PromoteTaskOutputFn;
+  readonly taskStatusAccumulator?: TaskStatusAccumulator;
+}
+
+function makeCtx(
+  awaitFn?: AwaitHumanInputFn,
+  emitFn?: EmitEventsFn,
+  options?: CtxOptions,
+): TaskExecutionContext {
   return {
-    evaluateExpressions: async () => ({}),
+    evaluateExpressions: options?.evaluateExpressions ?? (async () => ({})),
     doc: { document: { dsl: "1.0.0", name: "test" }, do: [] },
     sleep: notAvailable,
     listen: notAvailable,
@@ -27,6 +43,8 @@ function makeCtx(awaitFn?: AwaitHumanInputFn, emitFn?: EmitEventsFn): TaskExecut
     callFunction: notAvailable,
     callAgent: notAvailable,
     emitEvents: emitFn,
+    promoteTaskOutput: options?.promoteTaskOutput,
+    taskStatusAccumulator: options?.taskStatusAccumulator,
   };
 }
 
@@ -413,4 +431,232 @@ describe("executeHumanInputTask", () => {
       expect(resolved.outcome).toBe("approve");
     });
   });
+
+  describe("review payload", () => {
+    const awaitApprove: AwaitHumanInputFn = async () => ({ outcome: "approve" });
+
+    function gateWith(payload: unknown, uiHint?: string): HumanInputTaskDef {
+      return {
+        kind: "human_input",
+        humanInput: { prompt: "Review the material", payload, uiHint },
+      };
+    }
+
+    /** Captures emitted batches and returns the approval_requested event. */
+    function captureRequested(emitted: WorkflowEventDescriptor[][]) {
+      const requested = emitted[0].find((e) => e.type === "approval_requested");
+      if (!requested || requested.type !== "approval_requested") {
+        throw new Error("approval_requested not emitted");
+      }
+      return requested;
+    }
+
+    it("resolves a whole-value expression payload against workflow state", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      const state = createState();
+      state.context = { draft: { title: "Q3 plan", items: [1, 2, 3] } };
+
+      await executeHumanInputTask(
+        gateWith("${ $context.draft }", "plan-review"),
+        "gate", state,
+        makeCtx(awaitApprove, emitFn, { evaluateExpressions: evaluateExpressionBatch }),
+      );
+
+      const requested = captureRequested(emitted);
+      expect(requested.payload).toEqual({ title: "Q3 plan", items: [1, 2, 3] });
+      expect(requested.uiHint).toBe("plan-review");
+      expect(requested.payloadArtifactId).toBeUndefined();
+    });
+
+    it("records the uiHint on the task status entry so listPendingApprovals can badge by review type", async () => {
+      const accumulator = new TaskStatusAccumulator();
+      accumulator.taskStarted("gate", "human_input");
+
+      await executeHumanInputTask(
+        gateWith({ text: "inline" }, "plan-review"),
+        "gate", createState(),
+        makeCtx(awaitApprove, undefined, {
+          evaluateExpressions: evaluateExpressionBatch,
+          taskStatusAccumulator: accumulator,
+        }),
+      );
+
+      const entry = accumulator.toArray().find((e) => e.taskName === "gate");
+      expect(entry?.uiHint).toBe("plan-review");
+    });
+
+    it("resolves embedded expressions inside an inline object payload", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      const state = createState();
+      state.context = { triage: { severity: "P1" } };
+
+      await executeHumanInputTask(
+        gateWith({ summary: "Severity: ${ $context.triage.severity }", static: true }),
+        "gate", state,
+        makeCtx(awaitApprove, emitFn, { evaluateExpressions: evaluateExpressionBatch }),
+      );
+
+      const requested = captureRequested(emitted);
+      expect(requested.payload).toEqual({ summary: "Severity: P1", static: true });
+      expect(requested.uiHint).toBeUndefined();
+    });
+
+    it("does not re-evaluate literal ${ } text inside resolved payload data (injection safety)", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      // External data (e.g. a webhook body) containing literal expression
+      // syntax must survive resolution verbatim.
+      const state = createState();
+      state.context = { article: { body: "Use ${ .secrets.KEY } to authenticate" } };
+
+      await executeHumanInputTask(
+        gateWith("${ $context.article }"),
+        "gate", state,
+        makeCtx(awaitApprove, emitFn, { evaluateExpressions: evaluateExpressionBatch }),
+      );
+
+      const requested = captureRequested(emitted);
+      expect(requested.payload).toEqual({ body: "Use ${ .secrets.KEY } to authenticate" });
+    });
+
+    it("fails the task when payload resolution errors", async () => {
+      const failingEvaluator: ExpressionEvaluator = async () => {
+        throw new Error("jq: compile error");
+      };
+
+      await expect(
+        executeHumanInputTask(
+          gateWith("${ $context.draft | invalid_filter }"),
+          "gate", createState(),
+          makeCtx(awaitApprove, undefined, { evaluateExpressions: failingEvaluator }),
+        ),
+      ).rejects.toThrow("failed to resolve 'payload' expressions");
+    });
+
+    it("fails the task when payload resolves to null (missing context path)", async () => {
+      await expect(
+        executeHumanInputTask(
+          gateWith("${ $context.does_not_exist }"),
+          "gate", createState(),
+          makeCtx(awaitApprove, undefined, { evaluateExpressions: evaluateExpressionBatch }),
+        ),
+      ).rejects.toThrow("'payload' resolved to null");
+    });
+
+    it("promotes the payload and emits an artifact reference instead of inline data", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      const promoteFn: PromoteTaskOutputFn = vi.fn(async () => ({
+        output: { _artifact_ref: "art_review123" },
+        artifactIds: ["art_review123"],
+        artifactCreatedEvents: [{
+          type: "artifact_created" as const,
+          artifactId: "art_review123",
+          displayName: "gate — review-payload.json",
+          contentType: "application/json",
+          sizeBytes: 300_000,
+          occurredAt: new Date().toISOString(),
+        }],
+      }));
+
+      const state = createState();
+      state.context = { proposal: { records: ["huge"] } };
+
+      await executeHumanInputTask(
+        gateWith("${ $context.proposal }", "infra-proposal"),
+        "gate", state,
+        makeCtx(awaitApprove, emitFn, {
+          evaluateExpressions: evaluateExpressionBatch,
+          promoteTaskOutput: promoteFn,
+        }),
+      );
+
+      expect(promoteFn).toHaveBeenCalledWith(
+        { records: ["huge"] }, "", "gate", "gate — review-payload.json",
+      );
+
+      const requested = captureRequested(emitted);
+      expect(requested.payload).toBeUndefined();
+      expect(requested.payloadArtifactId).toBe("art_review123");
+      expect(requested.uiHint).toBe("infra-proposal");
+
+      const artifactEvent = emitted[0].find((e) => e.type === "artifact_created");
+      expect(artifactEvent).toBeDefined();
+      if (artifactEvent?.type !== "artifact_created") throw new Error("unexpected");
+      expect(artifactEvent.artifactId).toBe("art_review123");
+    });
+
+    it("delivers inline when the promotion activity returns no artifacts (below threshold)", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      const promoteFn: PromoteTaskOutputFn = async (taskOutput) => ({
+        output: taskOutput, artifactIds: [], artifactCreatedEvents: [],
+      });
+
+      const state = createState();
+      state.context = { note: "small" };
+
+      await executeHumanInputTask(
+        gateWith("${ $context.note }"),
+        "gate", state,
+        makeCtx(awaitApprove, emitFn, {
+          evaluateExpressions: evaluateExpressionBatch,
+          promoteTaskOutput: promoteFn,
+        }),
+      );
+
+      const requested = captureRequested(emitted);
+      expect(requested.payload).toBe("small");
+      expect(requested.payloadArtifactId).toBeUndefined();
+    });
+
+    it("falls back to inline delivery when promotion fails (best-effort policy)", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      const promoteFn: PromoteTaskOutputFn = async () => {
+        throw new Error("artifact store unavailable");
+      };
+
+      const state = createState();
+      state.context = { doc: { text: "content" } };
+
+      await executeHumanInputTask(
+        gateWith("${ $context.doc }"),
+        "gate", state,
+        makeCtx(awaitApprove, emitFn, {
+          evaluateExpressions: evaluateExpressionBatch,
+          promoteTaskOutput: promoteFn,
+        }),
+      );
+
+      const requested = captureRequested(emitted);
+      expect(requested.payload).toEqual({ text: "content" });
+      expect(requested.payloadArtifactId).toBeUndefined();
+    });
+
+    it("omits payload fields entirely when the task config has no payload", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Simple gate" },
+      };
+
+      await executeHumanInputTask(taskDef, "gate", createState(), makeCtx(awaitApprove, emitFn));
+
+      const requested = captureRequested(emitted);
+      expect(requested.payload).toBeUndefined();
+      expect(requested.uiHint).toBeUndefined();
+      expect(requested.payloadArtifactId).toBeUndefined();
+    });
+  });
 });

package/src/workflow-engine/loader.ts

@@ -520,5 +520,9 @@ function parseHumanInputConfig(taskName: string, raw: unknown): import("./types.
       : undefined,
     timeout: typeof obj.timeout === "number" ? obj.timeout : undefined,
     onTimeout: (obj.on_timeout as "fail" | "approve" | "deny") ?? undefined,
+    // Any JSON shape is a valid payload (expression string, object, array),
+    // so only null/undefined mean "no payload" here.
+    payload: obj.payload ?? undefined,
+    uiHint: typeof obj.ui_hint === "string" && obj.ui_hint ? obj.ui_hint : undefined,
   };
 }

package/src/workflow-engine/resolve.ts

@@ -301,8 +301,16 @@ function collectEmbeddedFromValue(
   batchExprs: Record<string, string>,
   skipPaths: Set<string>,
 ): void {
+  // A Phase-1-resolved path holds data, not template text: skip its
+  // entire subtree, whatever shape it resolved to. A strict expression
+  // can resolve to an object or array whose nested strings carry literal
+  // `${ ... }` text from external sources (webhook payloads, API
+  // responses, documents under review) that must never be re-interpreted
+  // as expressions. Checking only string values at the exact path — the
+  // previous behavior — left those nested strings exposed.
+  if (skipPaths.has(path)) return;
+
   if (typeof value === "string") {
-    if (skipPaths.has(path)) return;
     if (isStrictExpr(value)) return;
     const expressions = extractEmbeddedExpressions(value);
     if (expressions.length === 0) return;

package/src/workflow-engine/task-status-accumulator.ts

@@ -25,6 +25,13 @@ export interface TaskStatusEntry {
   readonly costMicros?: number;
   readonly inputTokens?: number;
   readonly outputTokens?: number;
+  /**
+   * Review-surface hint from the human_input task's ui_hint config.
+   * Set on the waiting_approval transition and retained through later
+   * transitions (spread semantics), so the persisted status keeps the
+   * record of what kind of review the gate presented.
+   */
+  readonly uiHint?: string;
 }
 
 /**
@@ -177,7 +184,7 @@ export class TaskStatusAccumulator {
     });
   }
 
-  taskWaitingApproval(name: string): void {
+  taskWaitingApproval(name: string, uiHint?: string): void {
     const existing = this.entries.get(name);
     this.entries.set(name, {
       ...existing,
@@ -186,6 +193,7 @@ export class TaskStatusAccumulator {
       taskKind: existing?.taskKind ?? "",
       status: "waiting_approval",
       startedAt: existing?.startedAt,
+      uiHint: uiHint ?? existing?.uiHint,
     });
   }
 

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

@@ -17,6 +17,8 @@
  *       call: human_input
  *       with:
  *         prompt: "Please review this deployment"
+ *         payload: ${ $context.deployment_plan }
+ *         ui_hint: deployment-plan
  *         timeout: 300
  *         on_timeout: approve
  *         outcomes:
@@ -24,16 +26,22 @@
  *           - name: deny
  *           - name: revise
  *             then: gatherMore
+ *
+ * The payload (the material under review) is expression-resolved at gate
+ * activation and attached to the approval_requested event — inline when
+ * small, as an artifact reference when at/above the promotion threshold —
+ * so the approval record captures exactly what the reviewer saw.
  */
 
 import type {
+  ArtifactCreatedEvent,
   HumanInputTaskDef,
   HumanInputConfig,
   WorkflowState,
   TaskExecutionContext,
   HumanInputResult,
 } from "../types.js";
-import { resolveEmbeddedExpressions } from "../resolve.js";
+import { resolveConfigExpressions, resolveEmbeddedExpressions } from "../resolve.js";
 import { isStrictExpr } from "../expression-utils.js";
 
 const SIGNAL_PREFIX = "human_input_";
@@ -60,25 +68,32 @@ export async function executeHumanInputTask(
   const resolvedPrompt = await resolvePromptExpressions(
     config.prompt, state, ctx,
   );
+  const review = await resolveReviewPayload(config, taskName, state, ctx);
 
   const approvalRequestedAt = Date.now();
 
-  ctx.taskStatusAccumulator?.taskWaitingApproval(taskName);
+  ctx.taskStatusAccumulator?.taskWaitingApproval(taskName, config.uiHint);
 
   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,
-    }]);
+    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,
+        payload: review.payload,
+        uiHint: config.uiHint,
+        payloadArtifactId: review.payloadArtifactId,
+      },
+      ...review.artifactEvents,
+    ]);
   }
 
   const result: HumanInputResult = await ctx.awaitHumanInput({
@@ -116,6 +131,87 @@ function validateConfig(config: HumanInputConfig, taskName: string): void {
   }
 }
 
+interface ResolvedReviewPayload {
+  /** Resolved payload for inline delivery on the approval_requested event. */
+  readonly payload?: unknown;
+  /** Artifact holding the payload when it exceeded the promotion threshold. */
+  readonly payloadArtifactId?: string;
+  /** artifact_created events to emit alongside approval_requested. */
+  readonly artifactEvents: readonly ArtifactCreatedEvent[];
+}
+
+const NO_REVIEW_PAYLOAD: ResolvedReviewPayload = { artifactEvents: [] };
+
+/**
+ * Resolves the review payload's `${ ... }` expressions and decides how it
+ * rides the approval_requested event: inline when small, or as an artifact
+ * reference when at/above the promotion threshold (256KB).
+ *
+ * Resolution goes through `resolveConfigExpressions` for its two-phase
+ * injection safety: review material resolved from `$context` (article
+ * drafts, webhook data) may contain literal `${ ... }` text that must
+ * never be re-evaluated as an expression.
+ *
+ * A resolution failure fails the task — a gate whose review material
+ * failed to materialize must not present an empty review. Promotion
+ * failure falls back to inline delivery (best-effort, matching the
+ * do-executor's task-output promotion policy).
+ */
+async function resolveReviewPayload(
+  config: HumanInputConfig,
+  taskName: string,
+  state: WorkflowState,
+  ctx: TaskExecutionContext,
+): Promise<ResolvedReviewPayload> {
+  if (config.payload === undefined || config.payload === null) {
+    return NO_REVIEW_PAYLOAD;
+  }
+
+  let resolved: unknown;
+  try {
+    const result = await resolveConfigExpressions(
+      { payload: config.payload }, null, state, ctx.evaluateExpressions,
+    );
+    resolved = result.payload;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `human_input task '${taskName}': failed to resolve 'payload' expressions: ${message}`,
+    );
+  }
+
+  // jq resolves missing paths to null rather than erroring. A configured
+  // payload that materializes as nothing is an authoring error (typically a
+  // wrong $context path) — fail loudly instead of presenting an empty review.
+  if (resolved === undefined || resolved === null) {
+    throw new Error(
+      `human_input task '${taskName}': 'payload' resolved to null — ` +
+      `check that the expression references existing workflow data`,
+    );
+  }
+
+  if (ctx.promoteTaskOutput) {
+    try {
+      const promotion = await ctx.promoteTaskOutput(
+        resolved,
+        state.env?.__stigmer_execution_id as string ?? "",
+        taskName,
+        `${taskName} — review-payload.json`,
+      );
+      if (promotion.artifactIds.length > 0) {
+        return {
+          payloadArtifactId: promotion.artifactIds[0],
+          artifactEvents: promotion.artifactCreatedEvents,
+        };
+      }
+    } catch {
+      // Promotion is best-effort; fall through to inline delivery.
+    }
+  }
+
+  return { payload: resolved, artifactEvents: [] };
+}
+
 /**
  * Resolves `${ ... }` expressions in the prompt string against the
  * current workflow state. Handles both strict (whole-value) and embedded

package/src/workflow-engine/types.ts

@@ -565,6 +565,14 @@ export interface HumanInputConfig {
   readonly approvers?: readonly string[];
   readonly timeout?: number;
   readonly onTimeout?: "fail" | "approve" | "deny";
+  /**
+   * Material for the reviewer to examine — a whole-value expression
+   * string, or an object/array with embedded expressions. Resolved at
+   * gate activation and attached to the approval_requested event.
+   */
+  readonly payload?: unknown;
+  /** Renderer discriminator forwarded verbatim to the approval UI. */
+  readonly uiHint?: string;
 }
 
 export interface HumanInputOutcome {
@@ -795,6 +803,14 @@ export interface ApprovalRequestedEvent extends EventBase {
   readonly timeoutSeconds: number;
   readonly outcomes: ReadonlyArray<{ name: string; label: string }>;
   readonly formSchema?: Record<string, unknown>;
+  /**
+   * Resolved review payload the gate presents. Mutually exclusive with
+   * payloadArtifactId — payloads at/above the promotion threshold live
+   * in the artifact store and only the reference rides the event.
+   */
+  readonly payload?: unknown;
+  readonly uiHint?: string;
+  readonly payloadArtifactId?: string;
 }
 
 export interface ApprovalResolvedEvent extends EventBase {
@@ -885,6 +901,8 @@ export type PromoteTaskOutputFn = (
   taskOutput: unknown,
   workflowExecutionId: string,
   taskName: string,
+  /** Artifact display name override; defaults to "<taskName> — output.json". */
+  displayName?: string,
 ) => Promise<PromoteTaskOutputResult>;
 
 // ─────────────────────────────────────────────────────────────────────

package/src/workflows/engine-core.ts

@@ -243,8 +243,8 @@ export async function runWorkflowEngine(
         taskName: agentMeta.taskName,
         workflowExecutionId: agentMeta.workflowExecutionId || executionId,
       }),
-    promoteTaskOutput: (taskOutput: unknown, wexId: string, taskName: string) =>
-      promoteProxy.PromoteTaskOutput(taskOutput, wexId || executionId, taskName),
+    promoteTaskOutput: (taskOutput: unknown, wexId: string, taskName: string, displayName?: string) =>
+      promoteProxy.PromoteTaskOutput(taskOutput, wexId || executionId, taskName, displayName),
   };
 
   const state = createState();