@stigmer/runner 3.1.10 → 3.1.11

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();