@codemation/core 0.11.1 → 0.13.0

package/dist/testing.cjs

@@ -1,8 +1,8 @@
-const require_di = require('./di-BlEKdoZS.cjs');
+const require_di = require('./di-C-2ep8NZ.cjs');
 require('./contracts-CK0x6w_G.cjs');
-const require_runtime = require('./runtime-DBzq5YBi.cjs');
+const require_runtime = require('./runtime-DjYXgOo0.cjs');
 const require_InMemoryRunEventBusRegistry = require('./InMemoryRunEventBusRegistry-Sa86VxuV.cjs');
-const require_bootstrap = require('./bootstrap-BxuTFTLB.cjs');
+const require_bootstrap = require('./bootstrap-BEu1fJBM.cjs');
 let tsyringe = require("tsyringe");
 tsyringe = require_di.__toESM(tsyringe);
 

package/dist/testing.d.cts

@@ -1,6 +1,6 @@
-import { $t as TriggerNodeConfig, A as RunResult, B as Container, Bt as NodeOutputs, Ci as CredentialSessionService, Ii as NodeId, Jn as NodeExecutionContext, K as TypeToken, Kt as RunDataFactory, Rn as ExecutionContextFactory, St as Items, Wt as ParentExecutionRef, Xt as RunnableNodeConfig, Yn as NodeExecutionRequest, Zn as NodeExecutionScheduler, _r as WorkflowRunnerService, ar as RunnableNodeExecuteArgs, at as EngineExecutionLimitsPolicy, bt as Item, cr as TriggerNode, ct as RunEventBus, fr as TriggerSetupStateRepository, ir as RunnableNode, rn as WorkflowDefinition, ur as TriggerSetupContext, z as WorkflowExecutionRepository, zi as WorkflowId, zt as NodeOffloadPolicy } from "./agentMcpTypes-ZiNbNsEi.cjs";
-import { n as InMemoryLiveWorkflowRepository, r as Engine, t as RunIntentService } from "./RunIntentService-CEF-sFfI.cjs";
-import { a as WorkflowSnapshotCodec, i as EngineWorkflowRunnerService, t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-Cggm5GVY.cjs";
+import { $t as RunnableNodeConfig, Cr as TriggerSetupStateRepository, Ct as Item, H as WorkflowExecutionRepository, Ht as NodeOffloadPolicy, N as RunResult, Or as WorkflowRunnerService, Pi as CredentialSessionService, Tt as Items, U as Container, Un as ExecutionContextFactory, Ut as NodeOutputs, Xi as WorkflowId, Y as TypeToken, Yt as RunDataFactory, ct as EngineExecutionLimitsPolicy, dt as RunEventBus, hr as RunnableNodeExecuteArgs, ir as NodeExecutionRequest, mr as RunnableNode, nn as TriggerNodeConfig, on as WorkflowDefinition, or as NodeExecutionScheduler, qi as NodeId, qt as ParentExecutionRef, rr as NodeExecutionContext, xr as TriggerSetupContext, yr as TriggerNode } from "./agentMcpTypes-DGIwk6Ue.cjs";
+import { n as InMemoryLiveWorkflowRepository, r as Engine, t as RunIntentService } from "./RunIntentService-BitgkKaT.cjs";
+import { a as WorkflowSnapshotCodec, i as EngineWorkflowRunnerService, t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-CqcTWexS.cjs";
 import { ZodType } from "zod";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 

package/dist/testing.d.ts

@@ -1,6 +1,6 @@
-import { $a as NodeId, Ba as CredentialSessionService, Di as TriggerSetupContext, Ln as Item, Pi as WorkflowRunnerService, Si as RunnableNodeExecuteArgs, Sn as EngineExecutionLimitsPolicy, Ti as TriggerNode, Tn as RunEventBus, br as WorkflowDefinition, di as NodeExecutionContext, fi as NodeExecutionRequest, gr as TriggerNodeConfig, ki as TriggerSetupStateRepository, ln as TypeToken, lr as RunDataFactory, mi as NodeExecutionScheduler, nn as WorkflowExecutionRepository, no as WorkflowId, nr as NodeOffloadPolicy, pr as RunnableNodeConfig, qt as RunResult, rn as Container, rr as NodeOutputs, sr as ParentExecutionRef, ti as ExecutionContextFactory, xi as RunnableNode, zn as Items } from "./index-zWGtEhrf.js";
-import { i as WorkflowSnapshotCodec, n as InMemoryLiveWorkflowRepository, r as EngineWorkflowRunnerService, t as RunIntentService, u as Engine } from "./RunIntentService-BVur7x9n.js";
-import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-BQbS9_gs.js";
+import { Eo as NodeId, Er as ParentExecutionRef, Fr as TriggerNodeConfig, Ii as NodeExecutionContext, Ji as RunnableNodeExecuteArgs, Li as NodeExecutionRequest, Mr as RunnableNodeConfig, On as TypeToken, Or as RunDataFactory, Qi as TriggerNode, Si as ExecutionContextFactory, Sn as Container, Sr as NodeOutputs, Vn as EngineExecutionLimitsPolicy, Wn as RunEventBus, ea as TriggerSetupContext, fn as RunResult, ir as Items, ko as WorkflowId, na as TriggerSetupStateRepository, nr as Item, po as CredentialSessionService, qi as RunnableNode, sa as WorkflowRunnerService, xn as WorkflowExecutionRepository, xr as NodeOffloadPolicy, zi as NodeExecutionScheduler, zr as WorkflowDefinition } from "./index-rllWL4r-.js";
+import { i as WorkflowSnapshotCodec, n as InMemoryLiveWorkflowRepository, r as EngineWorkflowRunnerService, t as RunIntentService, u as Engine } from "./RunIntentService-DYpqfu6D.js";
+import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-Cr75cSfL.js";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 import { ZodType } from "zod";
 

package/dist/testing.js

@@ -1,8 +1,8 @@
-import { d as CoreTokens } from "./di-0Wop7z1y.js";
+import { d as CoreTokens } from "./di-D9Mv3kF3.js";
 import "./contracts-DXdfTdpW.js";
-import { A as PersistedWorkflowTokenRegistry, B as DefaultExecutionContextFactory, C as DefaultDrivingScheduler, N as NodeExecutor, O as NodeInstanceFactory, R as InProcessRetryRunner, S as HintOnlyOffloadPolicy, W as AllWorkflowsActiveWorkflowActivationPolicy, a as InMemoryLiveWorkflowRepository, i as RunIntentService, k as WorkflowSnapshotCodec, l as Engine, ot as DefaultAsyncSleeper, p as InMemoryRunDataFactory, rt as emitPorts, vt as WorkflowBuilder, x as InlineDrivingScheduler } from "./runtime-cxmUkk0l.js";
+import { A as PersistedWorkflowTokenRegistry, C as DefaultDrivingScheduler, G as AllWorkflowsActiveWorkflowActivationPolicy, N as NodeExecutor, O as NodeInstanceFactory, S as HintOnlyOffloadPolicy, V as DefaultExecutionContextFactory, a as InMemoryLiveWorkflowRepository, i as RunIntentService, it as emitPorts, k as WorkflowSnapshotCodec, l as Engine, p as InMemoryRunDataFactory, st as DefaultAsyncSleeper, x as InlineDrivingScheduler, yt as WorkflowBuilder, z as InProcessRetryRunner } from "./runtime-6-U2Cou5.js";
 import { t as InMemoryRunEventBus } from "./InMemoryRunEventBusRegistry-Bwunvt1T.js";
-import { a as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-D_Yyi0wL.js";
+import { a as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-CSeInbj1.js";
 import { container } from "tsyringe";
 
 //#region src/testing/RejectingCredentialSessionService.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "publishConfig": {
     "access": "public"
   },

package/src/authoring/defineHumanApprovalNode.types.ts

@@ -0,0 +1,379 @@
+import type {
+  Duration,
+  ExecutionContext,
+  HumanTaskActor,
+  HumanTaskHandle,
+  HumanTaskSubject,
+  NodeExecutionContext,
+  ResumeContext,
+} from "../contracts/runtimeTypes";
+import type { Item, JsonValue, NodeInspectorSummaryRow, NodeConfigBase } from "../contracts/workflowTypes";
+import type { CredentialJsonRecord } from "../contracts/credentialTypes";
+import type { ZodObject, ZodType } from "zod";
+import type { DefinedNodeCredentialBindings } from "./defineNode.types";
+import { SuspensionRequest } from "../contracts/runtimeTypes";
+import { defineNode } from "./defineNode.types";
+import type { DefinedNode } from "./defineNode.types";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Decision shape merged into `item.json` after a HITL approval task resolves.
+ *
+ * - `"approved"` / `"rejected"` — from a human decision (uses `approvedPredicate`).
+ * - `"timed-out"` — timeout fired with `onTimeout: "halt"`.
+ * - `"auto-accepted"` — timeout fired with `onTimeout: "auto-accept"`.
+ */
+export interface HumanApprovalDecisionResult {
+  readonly status: "approved" | "rejected" | "timed-out" | "auto-accepted";
+  /** Identity of the person who decided; absent for automated outcomes. */
+  readonly actor?: HumanTaskActor;
+  /** ISO 8601 timestamp of the decision. */
+  readonly decidedAt?: Date;
+  /** Optional free-text note from the reviewer. */
+  readonly note?: string;
+  /**
+   * Full raw decision payload (only present for `"approved"` / `"rejected"`).
+   * Shape is determined by the channel's `decisionSchema`.
+   */
+  readonly payload?: Record<string, unknown>;
+}
+
+/**
+ * Output item shape emitted by a `defineHumanApprovalNode`-based node.
+ * Original `item.json` fields are preserved and `decision` is merged in.
+ * If the input `item.json` already contained a `decision` key it is **overwritten**.
+ */
+export type HumanApprovalOutputJson<TInputJson extends Record<string, unknown>> = TInputJson & {
+  readonly decision: HumanApprovalDecisionResult;
+};
+
+/**
+ * Extends {@link DefinedNode} with the `humanApprovalToolBehavior` metadata marker.
+ * Story 10 reads this field when attaching the node as an agent tool.
+ */
+export interface DefinedHumanApprovalNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson extends Record<string, unknown>,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+> extends DefinedNode<TKey, TConfig, TInputJson, HumanApprovalOutputJson<TInputJson>, TBindings> {
+  /**
+   * Behavior hint consumed by the agent runtime (story 10) when this node is attached as a tool.
+   * `"return"` (default) — return the rejection to the agent as a tool result.
+   * `"halt"` — halt the agent run on rejection.
+   *
+   * Standalone DSL usage ignores this field.
+   */
+  readonly humanApprovalToolBehavior: { onRejected: "return" | "halt" };
+}
+
+// ---------------------------------------------------------------------------
+// isHumanApprovalNode predicate
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when `node` was created by {@link defineHumanApprovalNode}.
+ * Uses the `humanApprovalToolBehavior` typed field as the discriminant.
+ */
+export function isHumanApprovalNode(
+  node: unknown,
+): node is DefinedHumanApprovalNode<string, Record<string, unknown>, Record<string, unknown>, undefined> {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    "humanApprovalToolBehavior" in node &&
+    typeof (node as { humanApprovalToolBehavior: unknown }).humanApprovalToolBehavior === "object"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// defineHumanApprovalNode
+// ---------------------------------------------------------------------------
+
+/**
+ * Authoring helper that compiles a HITL approval channel down to a regular
+ * {@link defineNode}-backed node with `SuspensionRequest` semantics.
+ *
+ * **Fast-forward decision semantics:**
+ * - On the first `execute` call (no `ctx.resumeContext`): throws a `SuspensionRequest`
+ *   that calls the author's `deliver`. The engine persists the suspension and continues.
+ * - On resume (`ctx.resumeContext` set): calls `onDecision`/`onTimeout` as appropriate,
+ *   merges a `decision` key into `item.json`, and returns an item with the original
+ *   `binary` map passed by reference (no copy).
+ *
+ * **Output shape per item:**
+ * ```ts
+ * // Input:  { json: { invoiceId: 42 }, binary?: {...} }
+ * // Output: { json: { invoiceId: 42, decision: { status: "approved", actor, decidedAt } }, binary: <unchanged> }
+ * ```
+ * If `item.json` already has a `decision` key it is **overwritten**. Namespace as
+ * needed if your schema reserves that key for another purpose.
+ *
+ * **Predicate persistence:**
+ * The `approvedPredicate` function is NOT serialized to the suspension record (except
+ * as an audit-only string via `toString()`). On resume, the workflow definition is
+ * reloaded from code at process start and the predicate closure is rebuilt naturally.
+ * If a deploy ships a changed predicate between suspend and resume, the *new* predicate
+ * runs — document this in your runbook when the predicate carries business logic that
+ * may change across deploys.
+ *
+ * @example
+ * ```ts
+ * export const slackApprovalNode = defineHumanApprovalNode({
+ *   key: "my-plugin.slackApproval",
+ *   title: "Slack Approval",
+ *   channel: "slack",
+ *   configSchema: z.object({ channel: z.string(), message: z.string() }),
+ *   decisionSchema: z.object({ approved: z.boolean(), note: z.string().optional() }),
+ *
+ *   async deliver({ task, config, item }, ctx) {
+ *     const ts = await postSlackMessage(config.channel, `Approve? <${task.resumeUrl}>`);
+ *     return { channel: config.channel, ts };
+ *   },
+ *
+ *   async onDecision({ decision, actor, delivery }, ctx) {
+ *     await updateSlackMessage(delivery.channel, delivery.ts, decision.approved ? "✅" : "❌");
+ *   },
+ * });
+ * ```
+ */
+export function defineHumanApprovalNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson extends Record<string, unknown>,
+  TDecision extends Record<string, unknown>,
+  TDelivery extends JsonValue,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+>(opts: {
+  key: TKey;
+  title: string;
+  description?: string;
+  icon?: string;
+  channel: string;
+
+  configSchema: ZodType<TConfig>;
+  inputSchema?: ZodType<TInputJson>;
+  decisionSchema: ZodType<TDecision>;
+  credentials?: TBindings;
+
+  /**
+   * Custom predicate that decides whether a decision counts as "approved".
+   * When omitted, the helper checks if `decisionSchema` is a Zod object with an
+   * `approved: boolean` field; if so it uses `decision.approved === true`.
+   * If neither holds, `defineHumanApprovalNode` throws at **definition time** (not runtime).
+   */
+  approvedPredicate?: (decision: TDecision) => boolean;
+  /** Default suspension timeout. Defaults to `"24h"`. */
+  defaultTimeout?: Duration;
+  /** What to do when the task times out. Defaults to `"halt"`. */
+  defaultOnTimeout?: "halt" | "auto-accept";
+
+  inspectorSummary?: (config: TConfig) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
+
+  deliver: (
+    args: {
+      task: HumanTaskHandle;
+      config: TConfig;
+      input: TInputJson;
+      item: Item;
+    },
+    ctx: ExecutionContext,
+  ) => Promise<TDelivery>;
+
+  onDecision?: (
+    args: {
+      decision: TDecision;
+      actor: HumanTaskActor;
+      task: HumanTaskHandle;
+      delivery: TDelivery;
+      item: Item;
+    },
+    ctx: ExecutionContext,
+  ) => Promise<void>;
+
+  onTimeout?: (
+    args: {
+      task: HumanTaskHandle;
+      delivery: TDelivery;
+      item: Item;
+      policy: "halt" | "auto-accept";
+    },
+    ctx: ExecutionContext,
+  ) => Promise<void>;
+}): DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings> {
+  // Resolve the approved predicate at definition time so we throw early when
+  // the schema is ambiguous.
+  const resolvedPredicate = resolveApprovedPredicate(opts.decisionSchema, opts.approvedPredicate);
+
+  const timeout = opts.defaultTimeout ?? "24h";
+  const onTimeout = opts.defaultOnTimeout ?? "halt";
+
+  // TOutputJson is `unknown` here because `execute` returns an Item-shaped object
+  // that the engine's NodeOutputNormalizer converts to the proper output. The public
+  // interface's DefinedHumanApprovalNode carries the correct output type for DSL use.
+  const inner = defineNode<TKey, TConfig, TInputJson, unknown, TBindings>({
+    key: opts.key,
+    title: opts.title,
+    description: opts.description,
+    icon: opts.icon,
+    configSchema: opts.configSchema,
+    inputSchema: opts.inputSchema,
+    credentials: opts.credentials,
+    inspectorSummary: opts.inspectorSummary ? ({ config }) => opts.inspectorSummary!(config) : undefined,
+
+    async execute(args, { config, execution: ctx }) {
+      if (!ctx.resumeContext) {
+        // First pass — suspend.
+        const subject = buildSubject(opts.title, args.item, ctx);
+        throw new SuspensionRequest({
+          decisionSchema: opts.decisionSchema,
+          timeout,
+          onTimeout,
+          subject,
+          metadata: {
+            channel: opts.channel,
+            nodeKey: opts.key,
+            // Stored for audit only; never re-evaluated. See JSDoc on defineHumanApprovalNode.
+            approvedPredicateSource: opts.approvedPredicate?.toString() ?? null,
+          },
+          deliver: (handle: HumanTaskHandle) =>
+            opts.deliver(
+              {
+                task: handle,
+                config,
+                input: args.input as TInputJson,
+                item: args.item,
+              },
+              ctx,
+            ),
+        });
+      }
+
+      // Resume pass.
+      return await handleResume(
+        args.item,
+        ctx.resumeContext,
+        opts.decisionSchema,
+        resolvedPredicate,
+        opts.onDecision,
+        opts.onTimeout,
+        ctx,
+      );
+    },
+  });
+
+  return Object.assign(inner, {
+    humanApprovalToolBehavior: { onRejected: "return" as const },
+  }) as unknown as DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers (module-private)
+// ---------------------------------------------------------------------------
+
+function resolveApprovedPredicate<TDecision extends Record<string, unknown>>(
+  schema: ZodType<TDecision>,
+  predicate: ((d: TDecision) => boolean) | undefined,
+): (d: TDecision) => boolean {
+  if (predicate) {
+    return predicate;
+  }
+  // Zod 4: ZodObject exposes `.shape` directly as an object (not a function).
+  const shape = (schema as unknown as ZodObject<Record<string, ZodType>>).shape;
+  if (shape && typeof shape === "object" && "approved" in shape) {
+    return (d) => (d as { approved?: unknown }).approved === true;
+  }
+  throw new Error(
+    `defineHumanApprovalNode: decisionSchema has no "approved" field and no approvedPredicate was provided. ` +
+      `Either add { approved: z.boolean() } to the decision schema or supply approvedPredicate explicitly.`,
+  );
+}
+
+function buildSubject(title: string, item: Item, ctx: NodeExecutionContext<NodeConfigBase>): HumanTaskSubject {
+  return {
+    title,
+    summary: "",
+    attributes: {
+      workflowId: ctx.workflowId,
+      nodeId: ctx.nodeId,
+      item: item.json as JsonValue,
+    },
+  };
+}
+
+function mergeDecision(
+  item: Item,
+  decision: HumanApprovalDecisionResult,
+): { json: Record<string, unknown>; binary: Item["binary"]; meta: Item["meta"] } {
+  return {
+    json: { ...(item.json as Record<string, unknown>), decision },
+    // binary is passed by reference — no copy. See defineHumanApprovalNode JSDoc.
+    binary: item.binary,
+    meta: item.meta,
+  };
+}
+
+async function handleResume<TDecision extends Record<string, unknown>, TDelivery extends JsonValue>(
+  item: Item,
+  resumeContext: ResumeContext,
+  decisionSchema: ZodType<TDecision>,
+  resolvedPredicate: (d: TDecision) => boolean,
+  onDecision:
+    | ((
+        args: {
+          decision: TDecision;
+          actor: HumanTaskActor;
+          task: HumanTaskHandle;
+          delivery: TDelivery;
+          item: Item;
+        },
+        ctx: ExecutionContext,
+      ) => Promise<void>)
+    | undefined,
+  onTimeoutCb:
+    | ((
+        args: {
+          task: HumanTaskHandle;
+          delivery: TDelivery;
+          item: Item;
+          policy: "halt" | "auto-accept";
+        },
+        ctx: ExecutionContext,
+      ) => Promise<void>)
+    | undefined,
+  ctx: ExecutionContext,
+): Promise<{ json: Record<string, unknown>; binary: Item["binary"]; meta: Item["meta"] }> {
+  const { decision: dec, delivery, task } = resumeContext;
+
+  if (dec.kind === "timed_out" || dec.kind === "auto_accepted") {
+    const policy: "halt" | "auto-accept" = dec.kind === "auto_accepted" ? "auto-accept" : "halt";
+    await onTimeoutCb?.({ task, delivery: delivery as TDelivery, item, policy }, ctx);
+    const status = dec.kind === "auto_accepted" ? "auto-accepted" : "timed-out";
+    return mergeDecision(item, { status, decidedAt: dec.at });
+  }
+
+  // dec.kind === "decided"
+  const parsed = decisionSchema.parse(dec.value);
+  await onDecision?.(
+    {
+      decision: parsed,
+      actor: dec.actor,
+      task,
+      delivery: delivery as TDelivery,
+      item,
+    },
+    ctx,
+  );
+
+  const isApproved = resolvedPredicate(parsed);
+  return mergeDecision(item, {
+    status: isApproved ? "approved" : "rejected",
+    actor: dec.actor,
+    decidedAt: dec.decidedAt,
+    note: (parsed as { note?: string }).note,
+    payload: parsed,
+  });
+}

package/src/authoring/index.ts

@@ -11,6 +11,12 @@ export type {
   DefineNodeOptions,
 } from "./defineNode.types";
 export { defineBatchNode, defineNode } from "./defineNode.types";
+export type {
+  DefinedHumanApprovalNode,
+  HumanApprovalDecisionResult,
+  HumanApprovalOutputJson,
+} from "./defineHumanApprovalNode.types";
+export { defineHumanApprovalNode, isHumanApprovalNode } from "./defineHumanApprovalNode.types";
 export type { DefineCredentialOptions } from "./defineCredential.types";
 export { defineCredential } from "./defineCredential.types";
 export { callableTool } from "./callableTool.types";

package/src/binaries/DefaultExecutionBinaryServiceFactory.ts

@@ -8,6 +8,7 @@ import type {
 } from "../types";
 
 import { DefaultNodeBinaryAttachmentService } from "./DefaultNodeBinaryAttachmentServiceFactory";
+import { boundedReadBinary } from "./boundedReadBinary.types";
 
 export class DefaultExecutionBinaryService implements ExecutionBinaryService {
   constructor(
@@ -28,8 +29,32 @@ export class DefaultExecutionBinaryService implements ExecutionBinaryService {
     );
   }
 
-  async openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined> {
-    return await this.storage.openReadStream(attachment.storageKey);
+  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined> {
+    return this.storage.openReadStream(attachment.storageKey);
+  }
+
+  async getBytes(attachment: BinaryAttachment, maxBytes?: number): Promise<Uint8Array> {
+    const stream = await this.openReadStream(attachment);
+    if (!stream) {
+      throw new Error("Binary attachment stream is unavailable.");
+    }
+    return boundedReadBinary(stream, attachment, maxBytes);
+  }
+
+  async getText(attachment: BinaryAttachment, maxBytes?: number): Promise<string> {
+    return new TextDecoder().decode(await this.getBytes(attachment, maxBytes));
+  }
+
+  async getJson<T = unknown>(attachment: BinaryAttachment, maxBytes?: number): Promise<T> {
+    const text = await this.getText(attachment, maxBytes);
+    try {
+      return JSON.parse(text) as T;
+    } catch (cause) {
+      throw new SyntaxError(
+        `Binary attachment at storage key "${attachment.storageKey}" is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+        { cause },
+      );
+    }
   }
 }
 

package/src/binaries/DefaultNodeBinaryAttachmentServiceFactory.ts

@@ -7,6 +7,8 @@ import type {
   NodeBinaryAttachmentService,
 } from "../types";
 
+import { readBinaryAsBytes, readBinaryAsJson, readBinaryAsText } from "./boundedReadBinary.types";
+
 export class DefaultNodeBinaryAttachmentService implements NodeBinaryAttachmentService {
   constructor(
     private readonly storage: BinaryStorage,
@@ -67,6 +69,18 @@ export class DefaultNodeBinaryAttachmentService implements NodeBinaryAttachmentS
     return await this.storage.openReadStream(attachment.storageKey);
   }
 
+  async getBytes(attachment: BinaryAttachment, maxBytes?: number): Promise<Uint8Array> {
+    return readBinaryAsBytes(this.storage, attachment, maxBytes);
+  }
+
+  async getText(attachment: BinaryAttachment, maxBytes?: number): Promise<string> {
+    return readBinaryAsText(this.storage, attachment, maxBytes);
+  }
+
+  async getJson<T = unknown>(attachment: BinaryAttachment, maxBytes?: number): Promise<T> {
+    return readBinaryAsJson<T>(this.storage, attachment, maxBytes);
+  }
+
   private createAttachmentId(): string {
     return DefaultNodeBinaryAttachmentService.createAttachmentIdValue(`${this.activationId}-${this.now().getTime()}`);
   }

package/src/binaries/boundedReadBinary.types.ts

@@ -0,0 +1,90 @@
+import type { BinaryAttachment, BinaryStorage } from "../types";
+import type { BinaryStorageReadResult } from "../types";
+import { BINARY_DEFAULT_MAX_BYTES } from "../contracts/runtimeTypes";
+
+/**
+ * Reads all bytes from an already-opened binary stream into a contiguous `Uint8Array`.
+ *
+ * Safety contract:
+ *  - `attachment.size` is checked against `maxBytes` *before* any allocation (no OOM).
+ *  - A single buffer of exactly `attachment.size` is pre-allocated; the stream fills it
+ *    directly — no chunks array, no doubling.
+ *  - A byte-count mismatch between the declared size and actual stream content is an error.
+ *
+ * This is the single canonical implementation; `ExecutionBinaryService.getBytes`,
+ * `getText`, and `getJson` all delegate here. The per-package `readBinaryBody` helpers
+ * in `core-nodes` and `core-nodes-ocr` have been removed in favour of this function.
+ */
+export async function boundedReadBinary(
+  result: BinaryStorageReadResult,
+  attachment: BinaryAttachment,
+  maxBytes: number = BINARY_DEFAULT_MAX_BYTES,
+): Promise<Uint8Array> {
+  if (attachment.size > maxBytes) {
+    throw new Error(
+      `Binary attachment size ${attachment.size} bytes exceeds maxBytes ${maxBytes}. ` +
+        `Raise the node's maxBytes setting if this document is expected to be larger.`,
+    );
+  }
+  const out = new Uint8Array(attachment.size);
+  const reader = result.body.getReader();
+  let offset = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    if (!value) {
+      continue;
+    }
+    if (offset + value.byteLength > out.byteLength) {
+      throw new Error(`Binary stream produced more bytes than the attachment's declared size (${attachment.size}).`);
+    }
+    out.set(value, offset);
+    offset += value.byteLength;
+  }
+  if (offset !== out.byteLength) {
+    throw new Error(`Binary stream produced ${offset} bytes but attachment declared size ${attachment.size}.`);
+  }
+  return out;
+}
+
+/** Shared implementation of `getBytes` used by both binary-service classes. */
+export async function readBinaryAsBytes(
+  storage: BinaryStorage,
+  attachment: BinaryAttachment,
+  maxBytes?: number,
+): Promise<Uint8Array> {
+  const result = await storage.openReadStream(attachment.storageKey);
+  if (!result) {
+    throw new Error("Binary attachment stream is unavailable.");
+  }
+  return boundedReadBinary(result, attachment, maxBytes);
+}
+
+/** Shared implementation of `getText` used by both binary-service classes. */
+export async function readBinaryAsText(
+  storage: BinaryStorage,
+  attachment: BinaryAttachment,
+  maxBytes?: number,
+): Promise<string> {
+  const bytes = await readBinaryAsBytes(storage, attachment, maxBytes);
+  return new TextDecoder().decode(bytes);
+}
+
+/** Shared implementation of `getJson` used by both binary-service classes. */
+export async function readBinaryAsJson<T = unknown>(
+  storage: BinaryStorage,
+  attachment: BinaryAttachment,
+  maxBytes?: number,
+): Promise<T> {
+  const text = await readBinaryAsText(storage, attachment, maxBytes);
+  try {
+    return JSON.parse(text) as T;
+  } catch (cause) {
+    throw new SyntaxError(
+      `Binary attachment at storage key "${attachment.storageKey}" is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause },
+    );
+  }
+}

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -13,6 +13,13 @@ import {
   NodeOutputNormalizer,
   RunnableOutputBehaviorResolver,
 } from "../../execution";
+import { NodeSuspensionHandler } from "../../execution/NodeSuspensionHandler";
+import { HumanTaskStoreToken } from "../../contracts/humanTaskStoreTypes";
+import {
+  HitlResumeTokenSignerToken,
+  HitlTimeoutJobSchedulerToken,
+  HitlWorkspaceIdToken,
+} from "../../contracts/hitlSeamTypes";
 import {
   EngineFactory,
   EngineWorkflowRunnerServiceFactory,
@@ -119,12 +126,34 @@ export class EngineRuntimeRegistrar {
         const retryRunner = dependencyContainer
           .resolve(InProcessRetryRunnerFactory)
           .create(dependencyContainer.resolve(DefaultAsyncSleeper));
+        const workflowExecutionRepository = dependencyContainer.resolve(CoreTokens.WorkflowExecutionRepository);
+        const humanTaskStore = dependencyContainer.isRegistered(HumanTaskStoreToken, true)
+          ? dependencyContainer.resolve(HumanTaskStoreToken)
+          : undefined;
+        const tokenSigner = dependencyContainer.isRegistered(HitlResumeTokenSignerToken, true)
+          ? dependencyContainer.resolve(HitlResumeTokenSignerToken)
+          : undefined;
+        const timeoutScheduler = dependencyContainer.isRegistered(HitlTimeoutJobSchedulerToken, true)
+          ? dependencyContainer.resolve(HitlTimeoutJobSchedulerToken)
+          : undefined;
+        const workspaceId = dependencyContainer.isRegistered(HitlWorkspaceIdToken, true)
+          ? dependencyContainer.resolve(HitlWorkspaceIdToken)
+          : undefined;
+        const suspensionHandler = new NodeSuspensionHandler(
+          workflowExecutionRepository,
+          humanTaskStore ?? undefined,
+          tokenSigner ?? undefined,
+          timeoutScheduler ?? undefined,
+          workspaceId ?? undefined,
+        );
         return dependencyContainer
           .resolve(NodeExecutorFactory)
           .create(
             dependencyContainer.resolve(CoreTokens.WorkflowNodeInstanceFactory),
             retryRunner,
             dependencyContainer.resolve(RunnableOutputBehaviorResolver),
+            suspensionHandler,
+            (runId) => workflowExecutionRepository.load(runId),
           );
       }),
     });