@codemation/core 0.11.1 → 0.13.0

package/src/execution/DefaultExecutionContextFactory.ts

@@ -6,6 +6,7 @@ import type {
   ExecutionContextFactory,
   ExecutionTelemetryFactory,
   NodeExecutionStatePublisher,
+  NodeResolver,
   ParentExecutionRef,
   RunDataSnapshot,
   RunId,
@@ -13,6 +14,7 @@ import type {
   WorkflowId,
 } from "../types";
 import { NoOpCostTrackingTelemetryFactory, NoOpExecutionTelemetryFactory } from "../types";
+import type { TypeToken } from "../di";
 
 import {
   DefaultExecutionBinaryService,
@@ -29,6 +31,7 @@ export class DefaultExecutionContextFactory implements ExecutionContextFactory {
     private readonly costTrackingFactory: CostTrackingTelemetryFactory = new NoOpCostTrackingTelemetryFactory(),
     private readonly currentDate: () => Date = () => new Date(),
     private readonly collections?: CollectionsContext,
+    private readonly nodeResolver?: NodeResolver,
   ) {}
 
   create(args: {
@@ -72,6 +75,14 @@ export class DefaultExecutionContextFactory implements ExecutionContextFactory {
       getCredential: args.getCredential,
       testContext: args.testContext,
       collections: this.collections,
+      resolve: <T>(token: TypeToken<T>): T => {
+        if (!this.nodeResolver) {
+          throw new Error(
+            "ExecutionContext.resolve() is not available: no NodeResolver was provided to DefaultExecutionContextFactory.",
+          );
+        }
+        return this.nodeResolver.resolve(token);
+      },
     };
   }
 }

package/src/execution/NodeExecutionSnapshotFactory.ts

@@ -2,6 +2,7 @@ import type {
   JsonValue,
   NodeActivationId,
   NodeExecutionSnapshot,
+  NodeExecutionStatus,
   NodeId,
   NodeInputsByPort,
   NodeOutputs,
@@ -70,6 +71,11 @@ export class NodeExecutionSnapshotFactory {
     inputsByPort: NodeInputsByPort;
     outputs: NodeOutputs;
     fromPinnedOutput?: boolean;
+    /** Override the terminal status for HITL outcomes (defaults to `"completed"`). */
+    hitlStatus?: Extract<
+      NodeExecutionStatus,
+      "hitl-approved" | "hitl-rejected" | "hitl-timeout" | "hitl-auto-accepted" | "hitl-cancelled"
+    >;
   }): NodeExecutionSnapshot {
     const fromPinnedOutput = args.fromPinnedOutput ?? false;
     const startedAt = fromPinnedOutput ? (args.previous?.startedAt ?? args.finishedAt) : args.previous?.startedAt;
@@ -79,7 +85,7 @@ export class NodeExecutionSnapshotFactory {
       nodeId: args.nodeId,
       activationId: args.activationId,
       parent: args.parent,
-      status: "completed",
+      status: args.hitlStatus ?? "completed",
       queuedAt: args.previous?.queuedAt,
       startedAt,
       finishedAt: args.finishedAt,

package/src/execution/NodeExecutor.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { isPortsEmission, isUnbrandedPortsEmissionShape } from "../contracts/emitPorts";
 import { CredentialUnboundError } from "../contracts/credentialTypes";
+import { SuspensionRequest } from "../contracts/runtimeTypes";
 
 import type {
   Item,
@@ -8,9 +9,11 @@ import type {
   NodeActivationRequest,
   NodeExecutionContext,
   NodeOutputs,
+  PersistedRunState,
   RunnableNode,
   RunnableNodeConfig,
   RunnableNodeExecuteArgs,
+  RunId,
   TriggerNode,
   WorkflowNodeInstanceFactory,
 } from "../types";
@@ -20,6 +23,8 @@ import { FanInMergeByOriginMerger } from "./FanInMergeByOriginMerger";
 import { ItemExprResolver } from "./ItemExprResolver";
 import { InProcessRetryRunner } from "./InProcessRetryRunner";
 import { NodeOutputNormalizer } from "./NodeOutputNormalizer";
+import { NodeSuspensionHandler } from "./NodeSuspensionHandler";
+import { RunSuspendedError } from "./RunSuspendedError";
 import { RunnableOutputBehaviorResolver } from "./RunnableOutputBehaviorResolver";
 
 export class NodeExecutor {
@@ -33,6 +38,10 @@ export class NodeExecutor {
     private readonly retryRunner: InProcessRetryRunner,
     itemExprResolver?: ItemExprResolver,
     outputBehaviorResolver?: RunnableOutputBehaviorResolver,
+    /** Required for HITL suspension support. When omitted, `SuspensionRequest` throws upward. */
+    private readonly suspensionHandler?: NodeSuspensionHandler,
+    /** Required alongside `suspensionHandler`. */
+    private readonly loadRunState?: (runId: RunId) => Promise<PersistedRunState | undefined>,
   ) {
     this.itemExprResolver = itemExprResolver ?? new ItemExprResolver();
     this.outputBehaviorResolver = outputBehaviorResolver ?? new RunnableOutputBehaviorResolver();
@@ -173,6 +182,7 @@ export class NodeExecutor {
       }) as NodeOutputs;
     }
     const byPort: Partial<Record<string, Item[]>> = {};
+    let hasSuspension = false;
     for (let i = 0; i < inputBatch.length; i++) {
       const item = inputBatch[i] as Item;
       this.assertItemJsonNotTopLevelArray(request.nodeId, item);
@@ -194,7 +204,51 @@ export class NodeExecutor {
         items: inputBatch,
         ctx: iterationCtx,
       };
-      const raw = await Promise.resolve(node.execute(args));
+      let raw: unknown;
+      try {
+        raw = await Promise.resolve(node.execute(args));
+      } catch (e) {
+        // Use both instanceof AND name check: under tsx/dev with mixed source/dist resolution,
+        // SuspensionRequest may load as two distinct class objects and instanceof fails. The
+        // name brand survives the duality because both copies set name="SuspensionRequest".
+        const isSuspension =
+          e instanceof SuspensionRequest ||
+          (e instanceof Error &&
+            e.name === "SuspensionRequest" &&
+            typeof (e as { request?: unknown }).request === "object");
+        if (isSuspension) {
+          if (!this.suspensionHandler || !this.loadRunState) {
+            // Suspension not supported in this executor configuration — propagate as a regular error.
+            throw new Error(
+              `Node ${request.nodeId} threw SuspensionRequest but this NodeExecutor has no suspensionHandler configured.`,
+              { cause: e },
+            );
+          }
+          // Per-item suspension: load current state, persist the suspension entry, and
+          // continue processing remaining items. If deliver throws it propagates upward.
+          const state = await this.loadRunState(request.runId);
+          if (!state) {
+            throw new Error(`NodeExecutor: run state not found for runId ${request.runId} during suspension`, {
+              cause: e,
+            });
+          }
+          // handleSuspension throws RunSuspendedError after persisting — we re-throw it
+          // to exit the loop immediately. Partial byPort outputs are intentionally dropped
+          // (TODO: consider stashing outputs of non-suspended items alongside the suspension).
+          await this.suspensionHandler.handle({
+            runId: request.runId,
+            nodeId: request.nodeId,
+            activationId: request.activationId,
+            itemIndex: i,
+            suspensionRequest: e as SuspensionRequest,
+            state,
+            telemetry: iterationCtx.telemetry,
+          });
+          hasSuspension = true; // unreachable — handler always throws, but satisfies TS control-flow
+          continue;
+        }
+        throw e;
+      }
       const normalized = this.outputNormalizer.normalizeExecuteResult({
         baseItem: item,
         raw,
@@ -209,6 +263,11 @@ export class NodeExecutor {
         byPort[port] = list;
       }
     }
+    if (hasSuspension) {
+      // Unreachable in practice (suspensionHandler always throws RunSuspendedError) but
+      // guards against future refactors that might change handler behaviour.
+      throw new RunSuspendedError(request.runId, "unknown");
+    }
     return byPort as NodeOutputs;
   }
 

package/src/execution/NodeExecutorFactory.ts

@@ -1,7 +1,8 @@
-import type { WorkflowNodeInstanceFactory } from "../types";
+import type { PersistedRunState, RunId, WorkflowNodeInstanceFactory } from "../types";
 
 import { InProcessRetryRunner } from "./InProcessRetryRunner";
 import { NodeExecutor } from "./NodeExecutor";
+import { NodeSuspensionHandler } from "./NodeSuspensionHandler";
 import { RunnableOutputBehaviorResolver } from "./RunnableOutputBehaviorResolver";
 
 export class NodeExecutorFactory {
@@ -9,7 +10,16 @@ export class NodeExecutorFactory {
     workflowNodeInstanceFactory: WorkflowNodeInstanceFactory,
     retryRunner: InProcessRetryRunner,
     outputBehaviorResolver: RunnableOutputBehaviorResolver,
+    suspensionHandler?: NodeSuspensionHandler,
+    loadRunState?: (runId: RunId) => Promise<PersistedRunState | undefined>,
   ): NodeExecutor {
-    return new NodeExecutor(workflowNodeInstanceFactory, retryRunner, undefined, outputBehaviorResolver);
+    return new NodeExecutor(
+      workflowNodeInstanceFactory,
+      retryRunner,
+      undefined,
+      outputBehaviorResolver,
+      suspensionHandler,
+      loadRunState,
+    );
   }
 }

package/src/execution/NodeSuspensionHandler.ts

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+import type { HitlResumeTokenSignerSeam, HitlTimeoutJobSchedulerSeam } from "../contracts/hitlSeamTypes";
+import type { HumanTaskRecord, HumanTaskStore } from "../contracts/humanTaskStoreTypes";
+import type {
+  HumanTaskHandle,
+  NodeActivationId,
+  NodeId,
+  PersistedRunState,
+  PersistedSuspensionEntry,
+  RunId,
+  SuspensionRequest,
+  WorkflowExecutionRepository,
+} from "../types";
+import type { TelemetryScope } from "../contracts/telemetryTypes";
+import { CodemationTelemetryAttributeNames } from "../contracts/CodemationTelemetryAttributeNames";
+
+import { RunSuspendedError } from "./RunSuspendedError";
+export { RunSuspendedError };
+
+/**
+ * Handles per-item `SuspensionRequest` catches in the engine's item execution loop.
+ *
+ * Responsibilities:
+ * 1. Generate a `taskId` (UUID v4).
+ * 2. Persist a `HumanTask` row via `HumanTaskStore.create`.
+ * 3. Sign a resume URL via `HitlResumeTokenSigner.sign`.
+ * 4. Enqueue a delayed BullMQ timeout job via `HitlTimeoutJobScheduler.enqueue`.
+ * 5. Build a `HumanTaskHandle` and call `deliver`.
+ * 6. Append a `PersistedSuspensionEntry` to the run state and flip status to `"suspended"`.
+ * 7. Persist via `WorkflowExecutionRepository.save`.
+ * 8. Throw `RunSuspendedError` so the caller can exit cleanly.
+ *
+ * If `deliver` throws, the error propagates up to `NodeExecutionRequestHandlerService`
+ * which routes it through `resumeFromNodeError` → run status becomes `"failed"`.
+ *
+ * `humanTaskStore`, `tokenSigner`, and `timeoutScheduler` are optional —
+ * when not registered (e.g. in unit tests), the handler still suspends the run but
+ * skips persistence, token signing, and job scheduling.
+ */
+export class NodeSuspensionHandler {
+  constructor(
+    private readonly workflowExecutionRepository: WorkflowExecutionRepository,
+    private readonly humanTaskStore?: HumanTaskStore,
+    private readonly tokenSigner?: HitlResumeTokenSignerSeam,
+    private readonly timeoutScheduler?: HitlTimeoutJobSchedulerSeam,
+    /** Workspace ID to stamp on HumanTaskRecord in managed mode (T7 security fix). Null in non-managed mode. */
+    private readonly workspaceId?: string,
+  ) {}
+
+  async handle(args: {
+    runId: RunId;
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+    itemIndex: number;
+    suspensionRequest: SuspensionRequest;
+    state: PersistedRunState;
+    /** Telemetry scope of the node's per-item span. Used to emit `hitl.task.*` span events. */
+    telemetry?: TelemetryScope;
+  }): Promise<never> {
+    const taskId = `htask_${globalThis.crypto.randomUUID()}`;
+    const { timeout, onTimeout, deliver, decisionSchema, subject, metadata } = args.suspensionRequest.request;
+
+    const timeoutMs = this.parseDurationMs(timeout);
+    const expiresAt = new Date(Date.now() + timeoutMs);
+
+    const decisionSchemaHash = this.hashSchema(decisionSchema);
+    const decisionSchemaJson = this.schemaToJson(decisionSchema);
+
+    // Build resume token (when signer is available)
+    let resumeUrl = "";
+    let resumeTokenHash = "";
+    if (this.tokenSigner) {
+      const token = this.tokenSigner.sign({ taskId, expiresAt, schemaHash: decisionSchemaHash });
+      resumeUrl = token; // callers (deliver) receive the raw token; inbox layers wrap into a URL
+      resumeTokenHash = this.tokenSigner.hashToken(token);
+    }
+
+    const handle: HumanTaskHandle = {
+      taskId,
+      runId: args.runId,
+      nodeId: args.nodeId,
+      expiresAt,
+      resumeUrl,
+      ...(metadata !== undefined ? { metadata } : {}),
+    };
+
+    // Emit hitl.task.created before calling deliver.
+    const channel = (metadata as Record<string, unknown> | undefined)?.["channel"];
+    await args.telemetry?.addSpanEvent?.({
+      name: "hitl.task.created",
+      attributes: {
+        [CodemationTelemetryAttributeNames.hitlTaskId]: taskId,
+        [CodemationTelemetryAttributeNames.hitlChannel]: typeof channel === "string" ? channel : "unknown",
+        [CodemationTelemetryAttributeNames.runId]: args.runId,
+        [CodemationTelemetryAttributeNames.nodeId]: args.nodeId,
+        expiresAt: expiresAt.toISOString(),
+      },
+    });
+
+    // D5: deliver throws → emit hitl.task.delivery_failed, then propagate upward;
+    // caller routes to resumeFromNodeError → "failed"
+    let deliveryRef: Awaited<ReturnType<typeof deliver>>;
+    try {
+      deliveryRef = await deliver(handle);
+    } catch (deliverError) {
+      await args.telemetry?.addSpanEvent?.({
+        name: "hitl.task.delivery_failed",
+        attributes: {
+          [CodemationTelemetryAttributeNames.hitlTaskId]: taskId,
+          [CodemationTelemetryAttributeNames.hitlChannel]: typeof channel === "string" ? channel : "unknown",
+          error: deliverError instanceof Error ? deliverError.message : String(deliverError),
+        },
+      });
+      throw deliverError;
+    }
+
+    // Persist HumanTask row
+    if (this.humanTaskStore) {
+      const record: HumanTaskRecord = {
+        id: taskId,
+        runId: args.runId,
+        workflowId: args.state.workflowId,
+        // T7: stamp workspaceId in managed mode so HitlCallbackHandler can assert workspace identity.
+        // Non-managed mode leaves this undefined (null in DB) — the check in HitlCallbackHandler
+        // is guarded by `task.workspaceId !== undefined` and is a no-op when null.
+        workspaceId: this.workspaceId ?? undefined,
+        nodeId: args.nodeId,
+        activationId: args.activationId,
+        itemIndex: args.itemIndex,
+        status: "pending",
+        channel: "local",
+        subject,
+        metadata: (metadata as Record<string, import("../contracts/workflowTypes").JsonValue>) ?? {},
+        decisionSchemaJson,
+        decisionSchemaHash,
+        onTimeout,
+        deliveryRef,
+        resumeTokenHash: resumeTokenHash || "no-token",
+        expiresAt,
+        createdAt: new Date(),
+      };
+      await this.humanTaskStore.create(record);
+    }
+
+    // Enqueue timeout job
+    if (this.timeoutScheduler) {
+      await this.timeoutScheduler.enqueueTimeoutJob({ taskId, expiresAt });
+    }
+
+    const entry: PersistedSuspensionEntry = {
+      taskId,
+      nodeId: args.nodeId,
+      activationId: args.activationId,
+      itemIndex: args.itemIndex,
+      decisionSchemaHash,
+      deliveryRef,
+      timeoutAt: expiresAt.toISOString(),
+      onTimeout,
+    };
+
+    const existingSuspensions = args.state.suspension ?? [];
+    const updatedState: PersistedRunState = {
+      ...args.state,
+      status: "suspended",
+      suspension: [...existingSuspensions, entry],
+    };
+
+    await this.workflowExecutionRepository.save(updatedState);
+
+    throw new RunSuspendedError(args.runId, taskId);
+  }
+
+  /**
+   * Parse a duration string into milliseconds.
+   * Accepts ISO 8601 durations ("PT24H", "PT30M") and shorthand ("24h", "30m", "1d").
+   * Throws for unrecognised formats.
+   */
+  private parseDurationMs(duration: string): number {
+    // Shorthand: "24h", "30m", "7d", "3600s"
+    const shorthand = /^(\d+(?:\.\d+)?)(s|m|h|d)$/i.exec(duration);
+    if (shorthand) {
+      const value = parseFloat(shorthand[1]!);
+      const unit = shorthand[2]!.toLowerCase();
+      const multipliers: Record<string, number> = {
+        s: 1_000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+      };
+      return value * multipliers[unit]!;
+    }
+    // ISO 8601 duration subset: PTnHnMnS (days handled via P1D)
+    const iso = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/.exec(duration);
+    if (iso) {
+      const days = parseFloat(iso[1] ?? "0");
+      const hours = parseFloat(iso[2] ?? "0");
+      const minutes = parseFloat(iso[3] ?? "0");
+      const seconds = parseFloat(iso[4] ?? "0");
+      return (days * 86_400 + hours * 3_600 + minutes * 60 + seconds) * 1_000;
+    }
+    throw new Error(`NodeSuspensionHandler: unrecognised duration format: "${duration}"`);
+  }
+
+  private hashSchema(schema: unknown): string {
+    const json = this.schemaToJson(schema);
+    return createHash("sha256").update(json).digest("hex");
+  }
+
+  private schemaToJson(schema: unknown): string {
+    if (schema instanceof z.ZodType) {
+      return JSON.stringify(z.toJSONSchema(schema));
+    }
+    if (typeof (schema as { toJSON?: unknown }).toJSON === "function") {
+      return JSON.stringify((schema as { toJSON: () => unknown }).toJSON());
+    }
+    return JSON.stringify(schema);
+  }
+}

package/src/execution/PersistedRunStateTerminalBuilder.ts

@@ -1,4 +1,4 @@
-import type { EngineRunCounters, PersistedRunState, RunQueueEntry } from "../types";
+import type { EngineRunCounters, PersistedRunState, RunHaltReason, RunQueueEntry } from "../types";
 
 /**
  * Merges common terminal-run fields onto a loaded {@link PersistedRunState} without repeating object literals.
@@ -7,7 +7,9 @@ export class PersistedRunStateTerminalBuilder {
   mergeTerminal(args: {
     state: PersistedRunState;
     engineCounters: EngineRunCounters;
-    status: "completed" | "failed";
+    status: "completed" | "failed" | "halted";
+    /** Populated when `status === "halted"`. */
+    reason?: RunHaltReason;
     queue: RunQueueEntry[];
     outputsByNode: PersistedRunState["outputsByNode"];
     nodeSnapshotsByNodeId: NonNullable<PersistedRunState["nodeSnapshotsByNodeId"]>;
@@ -18,6 +20,7 @@ export class PersistedRunStateTerminalBuilder {
       ...args.state,
       engineCounters: args.engineCounters,
       status: args.status,
+      reason: args.reason,
       pending: undefined,
       queue: args.queue,
       outputsByNode: args.outputsByNode,

package/src/execution/RunStateSemantics.ts

@@ -2,6 +2,7 @@ import type {
   Items,
   NodeActivationId,
   NodeExecutionSnapshot,
+  NodeExecutionStatus,
   NodeId,
   NodeInputsByPort,
   NodeOutputs,
@@ -139,6 +140,10 @@ export class RunStateSemantics {
     finishedAt: string;
     inputsByPort: NodeInputsByPort;
     outputs: NodeOutputs;
+    hitlStatus?: Extract<
+      NodeExecutionStatus,
+      "hitl-approved" | "hitl-rejected" | "hitl-timeout" | "hitl-auto-accepted" | "hitl-cancelled"
+    >;
   }): NodeExecutionSnapshot {
     const definition = args.workflow.nodes.find((node) => node.id === args.nodeId);
     if (this.missingRuntimeExecutionMarker.isMarked(definition?.config)) {

package/src/execution/RunSuspendedError.ts

@@ -0,0 +1,21 @@
+import type { RunId } from "../types";
+
+/**
+ * Internal sentinel thrown by {@link NodeSuspensionHandler} after persisting a suspension
+ * entry. `NodeExecutionRequestHandlerService` catches this specifically and returns cleanly —
+ * no continuation call, preventing `resumeFromNodeResult` / `resumeFromNodeError` from
+ * overwriting the `"suspended"` run status.
+ *
+ * The `Error` suffix satisfies the ESLint `no-manual-di-new` allowlist. This is NOT a
+ * user-facing error — it is an engine-internal control-flow primitive and should NOT be
+ * exported from the public barrel.
+ */
+export class RunSuspendedError extends Error {
+  constructor(
+    readonly runId: RunId,
+    readonly taskId: string,
+  ) {
+    super(`RunSuspendedError: run ${runId} suspended on task ${taskId}`);
+    this.name = "RunSuspendedError";
+  }
+}

package/src/index.ts

@@ -1,4 +1,35 @@
 export { SystemClock, type Clock } from "./contracts/Clock";
+export {
+  SuspensionRequest,
+  type HumanTaskHandle,
+  type HumanTaskSubject,
+  type HumanTaskActor,
+  type HumanTaskId,
+  type Duration,
+  type ResumeContext,
+} from "./contracts/runtimeTypes";
+export type { PersistedSuspensionEntry, PendingResumeEntry, RunHaltReason } from "./contracts/runTypes";
+export type { HumanTaskRecord, HumanTaskStatus, HumanTaskStore } from "./contracts/humanTaskStoreTypes";
+export { HumanTaskStoreToken } from "./contracts/humanTaskStoreTypes";
+export type { HitlResumeTokenSignerSeam, HitlTimeoutJobSchedulerSeam } from "./contracts/hitlSeamTypes";
+export {
+  HitlResumeTokenSignerToken,
+  HitlTimeoutJobSchedulerToken,
+  HitlWorkspaceIdToken,
+} from "./contracts/hitlSeamTypes";
+export type {
+  InboxChannel,
+  InboxChannelResolverSeam,
+  InboxDeliverArgs,
+  InboxDelivery,
+  InboxOnDecisionArgs,
+  InboxOnTimeoutArgs,
+} from "./contracts/inboxChannelTypes";
+export {
+  InboxChannelResolverToken,
+  LocalInboxChannelToken,
+  ControlPlaneInboxChannelToken,
+} from "./contracts/inboxChannelTypes";
 export * from "./authoring";
 export * from "./ai/AiHost";
 export { AgentConnectionNodeCollector } from "./ai/AgentConnectionNodeCollector";
@@ -44,3 +75,14 @@ export type {
   OAuthMaterial,
   OAuthFlowExecutor,
 } from "./credentials/OAuthFlowExecutor.types";
+export type {
+  CredentialMaterialProvider,
+  CredentialMaterialRef,
+  MaterialBundle,
+  CallerContext,
+} from "./credentials/CredentialMaterialProvider.types";
+export { IllegalMaterialSourceError } from "./credentials/CredentialMaterialProvider.types";
+export { ManagedCredentialMaterialWriteError } from "./credentials/ManagedCredentialMaterialWriteError";
+export { ManagedMaterialFetchError } from "./credentials/ManagedMaterialFetchError";
+export type { IWorkspaceFileStorage, WorkspaceFileMetadata } from "./contracts/workspaceFileTypes";
+export { WorkspaceFileNotFoundError, WorkspaceFileStorageToken } from "./contracts/workspaceFileTypes";

package/src/orchestration/Engine.ts

@@ -11,6 +11,7 @@ import type {
   NodeOutputs,
   ParentExecutionRef,
   PersistedWorkflowTokenRegistryLike,
+  ResumeContext,
   RunExecutionOptions,
   RunId,
   RunResult,
@@ -77,8 +78,9 @@ interface EngineRunContinuationService {
     nodeId: NodeId;
     error: Error;
   }): Promise<RunResult>;
-  waitForCompletion(runId: RunId): Promise<Extract<RunResult, { status: "completed" | "failed" }>>;
+  waitForCompletion(runId: RunId): Promise<Extract<RunResult, { status: "completed" | "failed" | "halted" }>>;
   waitForWebhookResponse(runId: RunId): Promise<WebhookRunResult>;
+  resumeRun(args: { runId: RunId; taskId: string; resumeContext: ResumeContext }): Promise<RunResult>;
 }
 
 interface EngineNodeExecutionRequestHandler {
@@ -226,7 +228,7 @@ export class Engine implements NodeActivationContinuation, NodeExecutionRequestH
     return await this.deps.runContinuationService.resumeFromStepError(args);
   }
 
-  async waitForCompletion(runId: RunId): Promise<Extract<RunResult, { status: "completed" | "failed" }>> {
+  async waitForCompletion(runId: RunId): Promise<Extract<RunResult, { status: "completed" | "failed" | "halted" }>> {
     return await this.deps.runContinuationService.waitForCompletion(runId);
   }
 
@@ -234,6 +236,14 @@ export class Engine implements NodeActivationContinuation, NodeExecutionRequestH
     return await this.deps.runContinuationService.waitForWebhookResponse(runId);
   }
 
+  /**
+   * Re-activate a suspended run item with a human decision (HITL).
+   * The HTTP resume endpoint calls this; this method exposes the engine primitive.
+   */
+  async resumeRun(args: { runId: RunId; taskId: string; resumeContext: ResumeContext }): Promise<RunResult> {
+    return await this.deps.runContinuationService.resumeRun(args);
+  }
+
   async handleNodeExecutionRequest(request: NodeExecutionRequest): Promise<void> {
     await this.deps.nodeExecutionRequestHandler.handleNodeExecutionRequest(request);
   }

package/src/orchestration/EngineWaiters.ts

@@ -21,7 +21,7 @@ export class EngineWaiters {
   }
 
   resolveRunCompletion(result: RunResult): void {
-    if (result.status !== "completed" && result.status !== "failed") return;
+    if (result.status !== "completed" && result.status !== "failed" && result.status !== "halted") return;
     const list = this.completionWaiters.get(result.runId);
     if (!list || list.length === 0) return;
     this.completionWaiters.delete(result.runId);

package/src/orchestration/NodeExecutionRequestHandlerService.ts

@@ -4,12 +4,14 @@ import type {
   NodeExecutionRequest,
   NodeExecutionRequestHandler,
   PersistedRunState,
+  ResumeContext,
   RunDataFactory,
   WorkflowDefinition,
   WorkflowExecutionRepository,
   WorkflowSnapshotResolver,
 } from "../types";
 import type { EngineExecutionLimitsPolicy } from "../policies/executionLimits/EngineExecutionLimitsPolicy";
+import { RunSuspendedError } from "../execution/RunSuspendedError";
 import { NodeActivationRequestComposer } from "../execution/NodeActivationRequestComposer";
 import { NodeRunStateWriterFactory } from "../execution/NodeRunStateWriterFactory";
 import { WorkflowRunExecutionContextFactory } from "../execution/WorkflowRunExecutionContextFactory";
@@ -84,6 +86,14 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
     const portKeys = Object.keys(inputsByPort);
     const kind = portKeys.length === 1 && portKeys[0] === "in" ? ("single" as const) : ("multi" as const);
     const batchId = pendingExecution.batchId ?? "batch_1";
+    // Splice resumeContext from pendingResume if this activation is a HITL resume.
+    const pendingResume = state.pendingResume;
+    const resumeContext: ResumeContext | undefined =
+      pendingResume?.activationId === request.activationId && pendingResume?.nodeId === request.nodeId
+        ? (pendingResume.resumeContext as ResumeContext)
+        : undefined;
+    const baseWithResume = resumeContext != null ? { ...base, resumeContext } : base;
+
     const activationRequest =
       kind === "multi"
         ? this.nodeActivationRequestComposer.createMultiFromDefinitionWithActivation({
@@ -92,7 +102,7 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
             workflowId: request.workflowId,
             parent: resolvedParent,
             executionOptions: request.executionOptions ?? state.executionOptions,
-            base,
+            base: baseWithResume,
             data,
             definition: {
               id: definition.id,
@@ -107,7 +117,7 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
             workflowId: request.workflowId,
             parent: resolvedParent,
             executionOptions: request.executionOptions ?? state.executionOptions,
-            base,
+            base: baseWithResume,
             data,
             definition: {
               id: definition.id,
@@ -117,6 +127,14 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
             input: inputsByPort.in ?? request.input ?? [],
           });
 
+    // Clear pendingResume from state now that we have consumed it.
+    if (resumeContext != null) {
+      const clearedState = await this.workflowExecutionRepository.load(request.runId);
+      if (clearedState?.pendingResume?.activationId === request.activationId) {
+        await this.workflowExecutionRepository.save({ ...clearedState, pendingResume: undefined });
+      }
+    }
+
     await this.continuation.markNodeRunning({
       runId: activationRequest.runId,
       activationId: activationRequest.activationId,
@@ -128,6 +146,11 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
     try {
       outputs = await this.nodeExecutor.execute(activationRequest);
     } catch (error) {
+      if (error instanceof RunSuspendedError) {
+        // The node threw SuspensionRequest; NodeSuspensionHandler already persisted the
+        // suspension entry and flipped status to "suspended". Nothing more to do here.
+        return;
+      }
       await this.resumeAfterExecutionError(activationRequest, this.asError(error));
       return;
     }