@codemation/core 0.11.1 → 0.12.0

package/src/contracts/inboxChannelTypes.ts

@@ -0,0 +1,58 @@
+import type { TypeToken } from "../di";
+import type { HumanTaskActor, HumanTaskHandle, HumanTaskSubject } from "./runtimeTypes";
+import type { Item } from "./workflowTypes";
+
+/**
+ * A single inbox delivery channel.
+ * Implementations: `LocalInboxChannel`, `ControlPlaneInboxChannel`.
+ */
+export interface InboxChannel {
+  readonly kind: "local" | "control-plane-inbox";
+  deliver(args: InboxDeliverArgs): Promise<InboxDelivery>;
+  updateOnDecision?(args: InboxOnDecisionArgs): Promise<void>;
+  updateOnTimeout?(args: InboxOnTimeoutArgs): Promise<void>;
+}
+
+export type InboxDeliverArgs = Readonly<{
+  task: HumanTaskHandle;
+  subject: HumanTaskSubject;
+  priority: "low" | "normal" | "high";
+  item: Item;
+  /** Present in managed mode (from `PairingConfig.workspaceId`). */
+  workspaceId?: string;
+}>;
+
+export type InboxDelivery =
+  | { kind: "local"; inboxItemId: string }
+  | { kind: "cp"; inboxItemId: string; workspaceId: string };
+
+export type InboxOnDecisionArgs = Readonly<{
+  delivery: InboxDelivery;
+  decision: { approved: boolean; note?: string };
+  actor: HumanTaskActor;
+}>;
+
+export type InboxOnTimeoutArgs = Readonly<{
+  delivery: InboxDelivery;
+  policy: "halt" | "auto-accept";
+}>;
+
+/**
+ * Resolves the correct `InboxChannel` for the current deployment mode
+ * (local dev vs. managed/CP). Implemented in `@codemation/host`.
+ */
+export interface InboxChannelResolverSeam {
+  resolve(): { channel: InboxChannel; workspaceId?: string };
+}
+
+export const InboxChannelResolverToken = Symbol.for("codemation.core.InboxChannelResolver") as TypeToken<
+  InboxChannelResolverSeam | undefined
+>;
+
+export const LocalInboxChannelToken = Symbol.for("codemation.core.LocalInboxChannel") as TypeToken<
+  InboxChannel | undefined
+>;
+
+export const ControlPlaneInboxChannelToken = Symbol.for("codemation.core.ControlPlaneInboxChannel") as TypeToken<
+  InboxChannel | undefined
+>;

package/src/contracts/index.ts

@@ -1,5 +1,8 @@
 export * from "./AgentBindError";
 export * from "./agentMcpTypes";
+export * from "./hitlSeamTypes";
+export * from "./humanTaskStoreTypes";
+export * from "./inboxChannelTypes";
 export * from "./NoOpAgentMcpIntegration";
 export * from "./baseTypes";
 export * from "./assertionTypes";

package/src/contracts/runTypes.ts

@@ -128,7 +128,18 @@ export interface RunQueueEntry {
   }>;
 }
 
-export type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+export type NodeExecutionStatus =
+  | "pending"
+  | "queued"
+  | "running"
+  | "completed"
+  | "failed"
+  | "skipped"
+  | "hitl-approved"
+  | "hitl-rejected"
+  | "hitl-timeout"
+  | "hitl-auto-accepted"
+  | "hitl-cancelled";
 
 export interface NodeExecutionError {
   message: string;
@@ -245,7 +256,10 @@ export interface ExecutionFrontierPlan {
   preservedPinnedNodeIds: ReadonlyArray<NodeId>;
 }
 
-export type RunStatus = "running" | "pending" | "completed" | "failed";
+export type RunStatus = "running" | "pending" | "completed" | "failed" | "suspended" | "halted";
+
+/** Reason a run transitioned to {@link RunStatus} `"halted"`. */
+export type RunHaltReason = "hitl-rejected" | "hitl-timeout" | "hitl-cancelled";
 
 export interface RunSummary {
   runId: RunId;
@@ -283,6 +297,37 @@ export interface PersistedRunSchedulingState {
   queue: RunQueueEntry[];
 }
 
+/** One persisted suspension entry per suspended item. */
+export interface PersistedSuspensionEntry {
+  /** Opaque task identifier (UUID v4). */
+  readonly taskId: string;
+  readonly nodeId: NodeId;
+  readonly activationId: NodeActivationId;
+  readonly itemIndex: number;
+  /** SHA-256 hex digest of the decision schema JSON (for schema-drift detection). */
+  readonly decisionSchemaHash: string;
+  /** Serialized return value from `SuspensionRequest.deliver` (stored on the HumanTask row). */
+  readonly deliveryRef: JsonValue;
+  /** ISO timestamp when the task expires. */
+  readonly timeoutAt: string;
+  readonly onTimeout: "halt" | "auto-accept";
+}
+
+/**
+ * When a node is re-activated after suspension, the engine writes the resume context here
+ * so `NodeExecutionRequestHandlerService` can splice `resumeContext` into ctx.
+ * Cleared once the re-activation is consumed.
+ */
+export interface PendingResumeEntry {
+  readonly activationId: NodeActivationId;
+  readonly nodeId: NodeId;
+  /**
+   * Typed as `unknown` here to avoid a circular import between runTypes ↔ runtimeTypes.
+   * `NodeExecutionRequestHandlerService` casts this to `ResumeContext` from runtimeTypes.
+   */
+  readonly resumeContext: unknown;
+}
+
 export interface PersistedRunState {
   runId: RunId;
   workflowId: WorkflowId;
@@ -301,12 +346,24 @@ export interface PersistedRunState {
   /** Successful node completions so far (for activation budget). */
   engineCounters?: EngineRunCounters;
   status: RunStatus;
+  /** Populated when `status === "halted"` to discriminate why the run was halted. */
+  reason?: RunHaltReason;
   pending?: PendingNodeExecution;
   queue: RunQueueEntry[];
   outputsByNode: Record<NodeId, NodeOutputs>;
   nodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
   /** Append-only history of connection invocations (LLM/tool) nested under owning nodes. */
   connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
+  /**
+   * One entry per outstanding HITL suspension (per-item).
+   * Present and non-empty iff `status === "suspended"`.
+   */
+  suspension?: ReadonlyArray<PersistedSuspensionEntry>;
+  /**
+   * Written by `resumeRun()` so `NodeExecutionRequestHandlerService` can splice `resumeContext`
+   * into the ctx when re-executing the suspended node. Cleared once consumed.
+   */
+  pendingResume?: PendingResumeEntry;
 }
 
 export interface WorkflowExecutionRepository {
@@ -349,7 +406,8 @@ export interface WorkflowExecutionPruneRepository {
 export type RunResult =
   | { runId: RunId; workflowId: WorkflowId; startedAt: string; status: "completed"; outputs: Items }
   | { runId: RunId; workflowId: WorkflowId; startedAt: string; status: "pending"; pending: PendingNodeExecution }
-  | { runId: RunId; workflowId: WorkflowId; startedAt: string; status: "failed"; error: { message: string } };
+  | { runId: RunId; workflowId: WorkflowId; startedAt: string; status: "failed"; error: { message: string } }
+  | { runId: RunId; workflowId: WorkflowId; startedAt: string; status: "halted"; reason: RunHaltReason };
 
 export type WebhookRunResult = Readonly<{
   runId: RunId;

package/src/contracts/runtimeTypes.ts

@@ -19,6 +19,105 @@ import type { WorkflowActivationPolicy } from "./workflowActivationPolicy";
 import type { TriggerInstanceId, WebhookTriggerMatcher } from "./webhookTypes";
 import type { ZodType } from "zod";
 
+// ---------------------------------------------------------------------------
+// HITL primitives
+// ---------------------------------------------------------------------------
+
+/** Opaque unique identifier for a single HumanTask instance. */
+export type HumanTaskId = string;
+
+/**
+ * Duration string — ISO 8601 duration ("PT24H") or shorthand ("24h").
+ * Parsed by the timeout job; stored as-is in the suspension record.
+ */
+export type Duration = string;
+
+/**
+ * Minimal handle handed to the `deliver` callback so it can route to the correct
+ * inbox channel.
+ */
+export interface HumanTaskHandle {
+  readonly taskId: HumanTaskId;
+  readonly runId: string;
+  readonly nodeId: string;
+  readonly expiresAt: Date;
+  /** TODO: real signed URL; placeholder empty string for now. */
+  readonly resumeUrl: string;
+  /**
+   * Arbitrary JSON metadata copied from `SuspensionRequest.request.metadata` at suspension time.
+   * Used by the agent runtime to round-trip the `agentCheckpoint` back to the
+   * resumed node via `ctx.resumeContext.task.metadata`.
+   */
+  readonly metadata?: Readonly<Record<string, import("./workflowTypes").JsonValue>>;
+}
+
+/** Human-readable description surface shown to the reviewer. */
+export interface HumanTaskSubject {
+  readonly title: string;
+  readonly summary: string;
+  readonly attributes?: import("./workflowTypes").JsonValue;
+}
+
+/** Identity of the person who made a decision on the task. */
+export interface HumanTaskActor {
+  readonly actorId: string;
+  readonly displayName?: string;
+}
+
+/**
+ * Resume context injected into `NodeExecutionContext` when the engine re-activates
+ * a previously suspended node. `defineHumanApprovalNode` wraps this with parsed
+ * `TDecision`; at the engine layer `decision.value` is `unknown`.
+ */
+export interface ResumeContext {
+  readonly decision:
+    | Readonly<{ kind: "decided"; value: unknown; actor: HumanTaskActor; decidedAt: Date }>
+    | Readonly<{ kind: "timed_out"; at: Date }>
+    | Readonly<{ kind: "auto_accepted"; at: Date }>;
+  readonly delivery: import("./workflowTypes").JsonValue;
+  readonly task: HumanTaskHandle;
+}
+
+/**
+ * Thrown by a node's `execute()` to request durable suspension of the current item.
+ * The engine catches this, persists the suspension entry, calls `deliver`, and
+ * continues to the next item (per-item semantics).
+ *
+ * @example
+ * ```ts
+ * throw new SuspensionRequest({
+ *   decisionSchema: z.object({ approved: z.boolean() }),
+ *   timeout: "PT24H",
+ *   onTimeout: "halt",
+ *   subject: { title: "Approve invoice", summary: "Invoice #1234 needs approval" },
+ *   deliver: async (handle) => {
+ *     await notifySlack(handle);
+ *     return { channel: "slack", ts: "..." };
+ *   },
+ * });
+ * ```
+ */
+export class SuspensionRequest<
+  TDecision = unknown,
+  TDelivery extends import("./workflowTypes").JsonValue = import("./workflowTypes").JsonValue,
+> extends Error {
+  constructor(
+    readonly request: Readonly<{
+      decisionSchema: ZodType<TDecision>;
+      timeout: Duration;
+      onTimeout: "halt" | "auto-accept";
+      subject: HumanTaskSubject;
+      metadata?: Readonly<Record<string, import("./workflowTypes").JsonValue>>;
+      deliver: (handle: HumanTaskHandle) => Promise<TDelivery>;
+    }>,
+  ) {
+    // Extending Error so wrappers like InProcessRetryRunner preserve identity
+    // (`instanceof SuspensionRequest`) instead of coercing via String(thrown).
+    super(`SuspensionRequest(${request.subject?.title ?? "untitled"})`);
+    this.name = "SuspensionRequest";
+  }
+}
+
 import type {
   ActivationIdFactory,
   BinaryAttachment,
@@ -183,6 +282,14 @@ export interface ExecutionContext {
    * Collections registered in the codemation config, keyed by collection name.
    */
   readonly collections?: CollectionsContext;
+  /**
+   * Resolve a DI token from the host container.
+   * Allows nodes to reach host-side services (e.g. `InboxChannelResolverToken`)
+   * without importing host code. Wired by `DefaultExecutionContextFactory`; throws
+   * a clear error when no resolver is configured (e.g. in unit tests that don't
+   * set up the full container).
+   */
+  resolve<T>(token: TypeToken<T>): T;
 }
 
 export interface ExecutionContextFactory {
@@ -208,6 +315,11 @@ export interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfi
   config: TConfig;
   telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
+  /**
+   * Present when this node activation is a HITL resume.
+   * The node checks `ctx.resumeContext !== undefined` and takes the resume branch.
+   */
+  resumeContext?: ResumeContext;
 }
 
 export interface PollingTriggerHandle {

package/src/credentials/CredentialMaterialProvider.types.ts

@@ -0,0 +1,61 @@
+import type { OAuthMaterial } from "./OAuthFlowExecutor.types";
+
+/**
+ * Material provider seam — see `docs/design/credentials-oauth-unification.md`,
+ * "Material provider seam" section. Sits beside the workspace's
+ * `CredentialStore`; persistence of the row stays at the store, persistence of
+ * the bytes goes through this provider so they can live at the control plane
+ * in managed mode.
+ */
+
+/**
+ * Pointer to material bytes. For local rows `ref` is the workspace instance id
+ * and the bytes co-locate with the row (existing `CredentialOAuth2Material` /
+ * `CredentialSecretMaterial` tables). For control-plane rows `ref` is the
+ * CP-side credential id; the workspace stores only the pointer.
+ */
+export type CredentialMaterialRef = Readonly<{
+  source: "local" | "control-plane";
+  id: string;
+}>;
+
+/**
+ * Decrypted material bytes returned by a provider. Shape matches
+ * `OAuthMaterial` — every supported credential type today is OAuth-shaped.
+ */
+export type MaterialBundle = OAuthMaterial;
+
+/**
+ * Caller context recorded by the CP material endpoint per fetch (D5 in the
+ * `credentials-vault` sprint README). The local provider accepts but ignores
+ * it; standalone mode has no audit log.
+ */
+export type CallerContext = Readonly<{
+  workspaceId: string;
+  caller:
+    | Readonly<{ kind: "workflow-node"; workflowId: string; nodeId: string }>
+    | Readonly<{ kind: "concierge"; chatId: string }>
+    | Readonly<{ kind: "research-agent"; chatId: string }>
+    | Readonly<{ kind: "manual"; userId: string }>;
+  reason?: string;
+}>;
+
+export interface CredentialMaterialProvider {
+  getMaterial(ref: CredentialMaterialRef, context: CallerContext): Promise<MaterialBundle>;
+  setMaterial(ref: CredentialMaterialRef, material: MaterialBundle): Promise<void>;
+}
+
+/**
+ * Thrown by a provider when asked to operate on a `ref.source` it does not
+ * handle (e.g. the local provider being asked to read `control-plane` bytes).
+ * Exported so `instanceof`-checks work across the workspace boundary.
+ */
+export class IllegalMaterialSourceError extends Error {
+  constructor(
+    public readonly source: CredentialMaterialRef["source"],
+    public readonly providerName: string,
+  ) {
+    super(`Provider "${providerName}" cannot handle material source "${source}".`);
+    this.name = "IllegalMaterialSourceError";
+  }
+}

package/src/credentials/ManagedCredentialMaterialWriteError.ts

@@ -0,0 +1,14 @@
+/**
+ * Thrown by managed-mode providers when `setMaterial` is called. Managed
+ * credential bytes are owned by the control plane; the workspace must not
+ * mutate them. See `docs/design/credentials-oauth-unification.md` and
+ * `planning/sprints/credentials-vault/02-controlplane-material-provider.md`.
+ */
+export class ManagedCredentialMaterialWriteError extends Error {
+  constructor(
+    message: string = "managed credentials are owned by the control plane; use the Connected apps page to create or modify them.",
+  ) {
+    super(message);
+    this.name = "ManagedCredentialMaterialWriteError";
+  }
+}

package/src/credentials/ManagedMaterialFetchError.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown by `ControlPlaneCredentialMaterialProvider` when the control-plane
+ * material endpoint returns a non-2xx response or a malformed body. Exposes
+ * the HTTP status and the raw error body so call sites can surface actionable
+ * detail without parsing strings.
+ */
+export class ManagedMaterialFetchError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly providerErrorBody: string,
+    message?: string,
+  ) {
+    super(message ?? `Control-plane material fetch failed: HTTP ${status} ${providerErrorBody}`);
+    this.name = "ManagedMaterialFetchError";
+  }
+}

package/src/execution/ActivationEnqueueService.ts

@@ -1,6 +1,8 @@
 import type {
   ConnectionInvocationRecord,
   EngineRunCounters,
+  PendingResumeEntry,
+  PersistedSuspensionEntry,
   PreparedNodeActivationDispatch,
   NodeActivationRequest,
   NodeActivationScheduler,
@@ -45,6 +47,16 @@ export type ActivationEnqueueRequest = {
   planner: RunQueuePlanner;
   engineCounters?: EngineRunCounters;
   connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
+  /**
+   * Remaining suspension entries after consuming one for a HITL resume.
+   * When provided, saved alongside the new pending state so they survive the enqueue.
+   */
+  suspension?: ReadonlyArray<PersistedSuspensionEntry>;
+  /**
+   * Resume context to attach to the re-activated node's execution context.
+   * Written here and consumed by `NodeExecutionRequestHandlerService` when building ctx.
+   */
+  pendingResume?: PendingResumeEntry;
 };
 
 export class ActivationEnqueueService {
@@ -114,6 +126,10 @@ export class ActivationEnqueueService {
         ...args.previousNodeSnapshotsByNodeId,
         [args.request.nodeId]: queuedSnapshot,
       },
+      // HITL: preserve suspension entries and resume context when re-activating a
+      // suspended node. Omit fields when not provided (avoids polluting normal enqueue).
+      ...(args.suspension !== undefined ? { suspension: args.suspension } : {}),
+      ...(args.pendingResume !== undefined ? { pendingResume: args.pendingResume } : {}),
     });
     await this.dispatchPreparedActivation(preparedDispatch);
     return {

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,
+    );
   }
 }