@codemation/core 0.11.0 → 0.12.0

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,12 @@ 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";

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;
     }