@codemation/core 0.11.1 → 0.12.0

package/dist/{index-62Ba9f7D.d.ts → index-BZDhEQ6W.d.ts}

@@ -1,6 +1,6 @@
-import { $ as CostCatalogEntry, $a as NodeId, $n as NodeInspectorSummaryRow, $r as ExecutionBinaryService, Ai as TriggerTestItemsContext, Ba as CredentialSessionService, Bi as WebhookInvocationMatch, Ct as ConnectionInvocationRecord, Da as CredentialFieldSchema, Dn as TestCaseRunStatus, En as RunEventSubscription, Fn as Edge, Ft as PersistedRunSchedulingState, Gi as WorkflowActivationPolicy, Gn as MutableRunData, Gr as BinaryStorage, Gt as RunPruneCandidate, Ha as CredentialType, Hr as RetryPolicySpec, In as ExecutionMode, It as PersistedRunState, Jn as NodeDefinition, Ki as ExecutionTelemetry, Kn as NodeActivationId, Kr as BinaryStorageReadResult, La as CredentialRequirement, Li as HttpMethod, Ln as Item, Mi as WorkflowRepository, Mn as ActivationIdFactory, Na as CredentialJsonRecord, Nn as BinaryAttachment, Oa as CredentialHealth, On as TestSuiteRunStatus, Ot as NodeExecutionSnapshot, Q as CostCatalog, Qt as RunTestContext, Ri as TriggerInstanceId, Rt as PersistedWorkflowSnapshotNode, Sa as AnyCredentialType, Sn as EngineExecutionLimitsPolicy, St as ConnectionInvocationId, Tn as RunEventBus, Tt as EngineRunCounters, Ua as CredentialTypeDefinition, Ui as WebhookTriggerRoutingDiagnostics, Vi as WebhookTriggerMatcher, Wa as CredentialTypeId, Wn as JsonValue, Wr as BinaryBody, Wt as RunExecutionOptions, Xr as EngineDeps, Ya as PollingTriggerLogger, Yr as BinaryStorageWriteResult, Zt as RunSummary, _a as CostTrackingTelemetryFactory, _i as NodeResolver, ai as NodeActivationContinuation, ar as NodeSchedulerDecision, bi as PreparedNodeActivationDispatch, br as WorkflowDefinition, cr as PersistedRunPolicySnapshot, di as NodeExecutionContext, dr as RunId, ei as ExecutionContext, en as WorkflowExecutionListingRepository, eo as OutputPortKey, fi as NodeExecutionRequest, gr as TriggerNodeConfig, ha as CostTrackingTelemetry, hi as NodeExecutionStatePublisher, ia as TelemetrySpanScope, ji as WorkflowNodeInstanceFactory, ki as TriggerSetupStateRepository, kn as TestSuiteRunId, li as NodeActivationScheduler, ln as TypeToken, lr as RunDataFactory, mi as NodeExecutionScheduler, nn as WorkflowExecutionRepository, no as WorkflowId, nr as NodeOffloadPolicy, nt as ParamDeep, pr as RunnableNodeConfig, qi as ExecutionTelemetryFactory, qn as NodeConfigBase, qr as BinaryStorageStatResult, qt as RunResult, rr as NodeOutputs, si as NodeActivationRequest, sr as ParentExecutionRef, ti as ExecutionContextFactory, tn as WorkflowExecutionPruneRepository, ui as NodeBinaryAttachmentService, ur as RunDataSnapshot, wn as RunEvent, xa as CollectionsContext, ya as CostTrackingUsageRecord, za as CredentialSessionFactoryArgs, zn as Items } from "./index-zWGtEhrf.js";
-import { i as WorkflowSnapshotCodec, u as Engine } from "./RunIntentService-BVur7x9n.js";
-import { B as ZodSchemaAny, K as CallableToolConfig, q as CallableToolConfigOptions } from "./ItemsInputNormalizer-_Mfcd3YU.js";
+import { $a as CredentialFieldSchema, $t as PersistedRunState, A as DefinedNodeCredentialAccessors, Aa as TelemetrySpanScope, Ar as RunId, Ci as HumanTaskHandle, Da as TelemetryScope, Dr as PersistedRunPolicySnapshot, Eo as OutputPortKey, Er as ParentExecutionRef, Fi as NodeExecutionContext, Fr as TriggerNodeConfig, Ga as CostTrackingUsageRecord, Gn as RunEventSubscription, Ii as NodeExecutionRequest, Ji as SuspensionRequest, Jn as TestSuiteRunId, Kn as TestCaseRunStatus, M as DefinedNodeCredentialBindings, Mr as RunnableNodeConfig, Ni as NodeActivationScheduler, O as DefinedNode, On as TypeToken, Oo as WorkflowId, Or as RunDataFactory, Pi as NodeBinaryAttachmentService, Qn as BinaryAttachment, Qt as PersistedRunSchedulingState, Ri as NodeExecutionScheduler, Rt as ConnectionInvocationId, Si as HumanTaskActor, Sr as NodeOutputs, Ti as HumanTaskSubject, To as NodeId, Ua as CostTrackingTelemetryFactory, Un as RunEvent, Va as CostTrackingTelemetry, Vi as NodeResolver, Vn as EngineExecutionLimitsPolicy, Vt as EngineRunCounters, Wi as PreparedNodeActivationDispatch, Wn as RunEventBus, Wt as NodeExecutionSnapshot, Zn as ActivationIdFactory, _a as WorkflowActivationPolicy, _n as RunTestContext, ao as CredentialJsonRecord, bi as ExecutionContext, bn as WorkflowExecutionPruneRepository, cn as RunExecutionOptions, di as BinaryStorageReadResult, do as CredentialSessionFactoryArgs, dr as NodeActivationId, eo as CredentialHealth, er as Edge, fa as WebhookInvocationMatch, fi as BinaryStorageStatResult, fn as RunResult, fo as CredentialSessionService, fr as NodeConfigBase, gi as EngineDeps, gn as RunSummary, ha as WebhookTriggerRoutingDiagnostics, ho as CredentialTypeDefinition, ht as CostCatalogEntry, ia as WorkflowRepository, ir as Items, ji as NodeActivationRequest, ki as NodeActivationContinuation, kr as RunDataSnapshot, la as HttpMethod, li as BinaryBody, lo as CredentialRequirement, lr as JsonValue, mi as BinaryStorageWriteResult, mo as CredentialType, mt as CostCatalog, na as TriggerTestItemsContext, nn as PersistedWorkflowSnapshotNode, nr as Item, pa as WebhookTriggerMatcher, pr as NodeDefinition, qa as CollectionsContext, qn as TestSuiteRunStatus, ra as WorkflowNodeInstanceFactory, si as RetryPolicySpec, ta as TriggerSetupStateRepository, tr as ExecutionMode, ua as TriggerInstanceId, ui as BinaryStorage, un as RunPruneCandidate, ur as MutableRunData, va as ExecutionTelemetry, vr as NodeInspectorSummaryRow, wr as NodeSchedulerDecision, xi as ExecutionContextFactory, xn as WorkflowExecutionRepository, xo as PollingTriggerLogger, xr as NodeOffloadPolicy, ya as ExecutionTelemetryFactory, yi as ExecutionBinaryService, yn as WorkflowExecutionListingRepository, zi as NodeExecutionStatePublisher, zr as WorkflowDefinition, zt as ConnectionInvocationRecord } from "./index-CSKKuK60.js";
+import { i as WorkflowSnapshotCodec, u as Engine } from "./RunIntentService-BOSGwmqn.js";
+import { B as ZodSchemaAny, K as CallableToolConfig, q as CallableToolConfigOptions } from "./ItemsInputNormalizer-C09a7iFP.js";
 import { ZodType, z } from "zod";
 
 //#region src/orchestration/AbortControllerFactory.d.ts
@@ -36,102 +36,136 @@ declare class SystemClock implements Clock {
   now(): Date;
 }
 //#endregion
-//#region src/authoring/defineNode.types.d.ts
-type MaybePromise$2<TValue> = TValue | Promise<TValue>;
-type ResolvableCredentialType = AnyCredentialType | CredentialTypeId;
-type SessionForCredentialType<TCredential extends ResolvableCredentialType> = TCredential extends AnyCredentialType ? Awaited<ReturnType<TCredential["createSession"]>> : unknown;
-type DefinedNodeCredentialBinding = ResolvableCredentialType | Readonly<{
-  readonly type: ResolvableCredentialType | ReadonlyArray<ResolvableCredentialType>;
-  readonly label?: string;
-  readonly optional?: true;
-  readonly helpText?: string;
-  readonly helpUrl?: string;
-}>;
-type DefinedNodeCredentialBindings = Readonly<Record<string, DefinedNodeCredentialBinding>>;
-type SessionForBinding<TBinding extends DefinedNodeCredentialBinding> = TBinding extends Readonly<{
-  type: infer TType;
-}> ? TType extends ReadonlyArray<infer TEntry> ? SessionForCredentialType<TEntry & ResolvableCredentialType> : SessionForCredentialType<TType & ResolvableCredentialType> : SessionForCredentialType<TBinding & ResolvableCredentialType>;
-type DefinedNodeCredentialAccessors<TBindings extends DefinedNodeCredentialBindings | undefined> = TBindings extends DefinedNodeCredentialBindings ? Readonly<{ [TKey in keyof TBindings]: () => Promise<SessionForBinding<TBindings[TKey]>> }> : Readonly<Record<string, never>>;
-interface DefinedNodeRunContext<TConfig$1 extends CredentialJsonRecord, TBindings extends DefinedNodeCredentialBindings | undefined> {
-  readonly config: TConfig$1;
-  readonly credentials: DefinedNodeCredentialAccessors<TBindings>;
-  readonly execution: NodeExecutionContext<RunnableNodeConfig<TConfig$1, unknown>>;
+//#region src/contracts/humanTaskStoreTypes.d.ts
+type HumanTaskStatus = "pending" | "decided" | "timed_out" | "auto_accepted" | "cancelled";
+/** Persisted record for a single HITL task instance. */
+interface HumanTaskRecord {
+  readonly id: string;
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly workspaceId?: string;
+  readonly nodeId: string;
+  readonly activationId: string;
+  readonly itemIndex: number;
+  readonly status: HumanTaskStatus;
+  readonly channel: string;
+  readonly subject: HumanTaskSubject;
+  readonly metadata: Record<string, JsonValue>;
+  readonly decisionSchemaJson: string;
+  readonly decisionSchemaHash: string;
+  readonly onTimeout: "halt" | "auto-accept";
+  readonly deliveryRef?: JsonValue;
+  readonly decision?: JsonValue;
+  readonly decidedAt?: Date;
+  readonly decidedBy?: HumanTaskActor;
+  readonly resumeTokenHash: string;
+  readonly expiresAt: Date;
+  readonly createdAt: Date;
+}
+interface HumanTaskStore {
+  create(record: HumanTaskRecord): Promise<void>;
+  findById(taskId: string): Promise<HumanTaskRecord | undefined>;
+  findByResumeTokenHash(tokenHash: string): Promise<HumanTaskRecord | undefined>;
+  findPendingForWorkspace(workspaceId: string): Promise<ReadonlyArray<HumanTaskRecord>>;
+  /** Returns all pending tasks regardless of workspace. Used by the local dev inbox (non-managed mode). */
+  findAllPending(): Promise<ReadonlyArray<HumanTaskRecord>>;
+  markDecided(args: {
+    taskId: string;
+    decision: JsonValue;
+    decidedBy: HumanTaskActor;
+    decidedAt: Date;
+  }): Promise<void>;
+  markTimedOut(taskId: string): Promise<void>;
+  markAutoAccepted(taskId: string): Promise<void>;
+  markCancelled(taskId: string): Promise<void>;
+  cancelPendingForRun(runId: string): Promise<void>;
 }
+declare const HumanTaskStoreToken: TypeToken<HumanTaskStore | undefined>;
+//#endregion
+//#region src/contracts/hitlSeamTypes.d.ts
 /**
- * Arguments for {@link defineNode} `execute` (engine `ctx` matches {@link RunnableNode.execute};
- * the second callback parameter adds {@link DefinedNodeRunContext} for credential accessors).
+ * Seam interfaces for HITL collaborators that are implemented in `@codemation/host`
+ * and injected into `NodeSuspensionHandler` at runtime. Core defines the interface only —
+ * no HTTP, vendor SDK, or Prisma dependencies here.
  */
-type DefineNodeExecuteArgs<TConfig$1 extends CredentialJsonRecord, TInputJson> = Readonly<{
-  input: TInputJson;
-  item: Item;
-  itemIndex: number;
-  items: Items;
-  ctx: NodeExecutionContext<RunnableNodeConfig<TInputJson, unknown> & Readonly<{
-    config: TConfig$1;
-  }>>;
-}>;
-type DefinedNodeConfigInput<TConfigResolved extends CredentialJsonRecord, TItemJson> = ParamDeep<TConfigResolved, TItemJson>;
-interface DefinedNode<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TInputJson, TOutputJson, _TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
-  readonly kind: "defined-node";
-  readonly key: TKey$1;
-  readonly title: string;
-  readonly description?: string;
-  create<TConfigItemJson = TInputJson>(config: DefinedNodeConfigInput<TConfig$1, TConfigItemJson>, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson>;
-  register(context: {
-    registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void;
-  }): void;
+/** Signs and hashes a HITL resume token. Core only needs the sign and hash operations. */
+interface HitlResumeTokenSignerSeam {
+  sign(args: {
+    taskId: string;
+    expiresAt: Date;
+    schemaHash: string;
+  }): string;
+  hashToken(token: string): string;
+}
+/** Schedules a delayed BullMQ job that drives the timeout path. */
+interface HitlTimeoutJobSchedulerSeam {
+  enqueueTimeoutJob(args: {
+    taskId: string;
+    expiresAt: Date;
+  }): Promise<void>;
 }
+declare const HitlResumeTokenSignerToken: TypeToken<HitlResumeTokenSignerSeam | undefined>;
+declare const HitlTimeoutJobSchedulerToken: TypeToken<HitlTimeoutJobSchedulerSeam | undefined>;
 /**
- * Plugin / DSL-friendly node: per-item `execute` with optional {@link RunnableNodeConfig.inputSchema}.
+ * Optional workspace ID injected into NodeSuspensionHandler in managed mode (T7 security fix).
+ * Allows the handler to stamp the workspaceId on each HumanTaskRecord so HitlCallbackHandler
+ * can assert workspace identity independently of the HMAC middleware.
+ * Not registered in non-managed mode; NodeSuspensionHandler defaults to null.
  */
-interface DefineNodeOptions<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TInputJson, TOutputJson, TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
-  readonly key: TKey$1;
-  readonly title: string;
-  readonly description?: string;
-  /**
-   * Canvas icon for this node (same contract as `NodeConfigBase.icon` on runnable configs).
-   * The Next host resolves Lucide (`lucide:…`), built-in SVGs (`builtin:…`), Simple Icons (`si:…`), and image URLs (`https:`, `data:`, `/…`).
-   */
-  readonly icon?: string;
-  /** Default values / form hints for **static** node configuration (credentials, retry, IDs), not per-item payload. */
-  readonly input?: Readonly<Record<keyof TConfig$1 & string, unknown>>;
-  readonly configSchema?: z.ZodType<TConfig$1>;
-  readonly credentials?: TBindings;
-  /**
-   * Validates **`input`** (engine also accepts `inputSchema` on the node class).
-   */
-  readonly inputSchema?: ZodType<TInputJson>;
-  /** Preserve inbound `item.binary` when `execute` returns plain JSON or item-shaped results without `binary`. */
-  readonly keepBinaries?: boolean;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — see
-   * {@link import("../contracts/workflowTypes").NodeConfigBase.inspectorSummary}.
-   *
-   * Receives the static config; returns 2–6 short label/value pairs (or `undefined` to skip).
-   */
-  readonly inspectorSummary?: (args: Readonly<{
-    config: TConfig$1;
-  }>) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
-  execute(args: DefineNodeExecuteArgs<TConfig$1, TInputJson>, context: DefinedNodeRunContext<TConfig$1, TBindings>): MaybePromise$2<TOutputJson>;
-}
+declare const HitlWorkspaceIdToken: TypeToken<string | undefined>;
+//#endregion
+//#region src/contracts/inboxChannelTypes.d.ts
 /**
- * Batch-oriented defined node: `run` receives all item JSON once (last item in activation); emits one output per input row.
+ * A single inbox delivery channel.
+ * Implementations: `LocalInboxChannel`, `ControlPlaneInboxChannel`.
  */
-interface DefineBatchNodeOptions<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TInputJson, TOutputJson, TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
-  readonly key: TKey$1;
-  readonly title: string;
-  readonly description?: string;
-  readonly icon?: string;
-  readonly input?: Readonly<Record<keyof TConfig$1 & string, unknown>>;
-  readonly configSchema?: z.ZodType<TConfig$1>;
-  readonly credentials?: TBindings;
-  readonly inspectorSummary?: (args: Readonly<{
-    config: TConfig$1;
-  }>) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
-  run(items: ReadonlyArray<TInputJson>, context: DefinedNodeRunContext<TConfig$1, TBindings>): MaybePromise$2<ReadonlyArray<TOutputJson>>;
-}
-declare function defineNode<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TInputJson, TOutputJson, TBindings extends DefinedNodeCredentialBindings | undefined = undefined>(options: DefineNodeOptions<TKey$1, TConfig$1, TInputJson, TOutputJson, TBindings>): DefinedNode<TKey$1, TConfig$1, TInputJson, TOutputJson, TBindings>;
-declare function defineBatchNode<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TInputJson, TOutputJson, TBindings extends DefinedNodeCredentialBindings | undefined = undefined>(options: DefineBatchNodeOptions<TKey$1, TConfig$1, TInputJson, TOutputJson, TBindings>): DefinedNode<TKey$1, TConfig$1, TInputJson, TOutputJson, TBindings>;
+interface InboxChannel {
+  readonly kind: "local" | "control-plane-inbox";
+  deliver(args: InboxDeliverArgs): Promise<InboxDelivery>;
+  updateOnDecision?(args: InboxOnDecisionArgs): Promise<void>;
+  updateOnTimeout?(args: InboxOnTimeoutArgs): Promise<void>;
+}
+type InboxDeliverArgs = Readonly<{
+  task: HumanTaskHandle;
+  subject: HumanTaskSubject;
+  priority: "low" | "normal" | "high";
+  item: Item;
+  /** Present in managed mode (from `PairingConfig.workspaceId`). */
+  workspaceId?: string;
+}>;
+type InboxDelivery = {
+  kind: "local";
+  inboxItemId: string;
+} | {
+  kind: "cp";
+  inboxItemId: string;
+  workspaceId: string;
+};
+type InboxOnDecisionArgs = Readonly<{
+  delivery: InboxDelivery;
+  decision: {
+    approved: boolean;
+    note?: string;
+  };
+  actor: HumanTaskActor;
+}>;
+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`.
+ */
+interface InboxChannelResolverSeam {
+  resolve(): {
+    channel: InboxChannel;
+    workspaceId?: string;
+  };
+}
+declare const InboxChannelResolverToken: TypeToken<InboxChannelResolverSeam | undefined>;
+declare const LocalInboxChannelToken: TypeToken<InboxChannel | undefined>;
+declare const ControlPlaneInboxChannelToken: TypeToken<InboxChannel | undefined>;
 //#endregion
 //#region src/authoring/DefinedNodeRegistry.d.ts
 declare class DefinedNodeRegistry {
@@ -264,12 +298,12 @@ type DefinePollingTriggerTestItemsContext<TConfig$1 extends TriggerNodeConfig<an
 /**
  * Options accepted by `definePollingTrigger`.
  */
-interface DefinePollingTriggerOptions<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TItemJson, TState extends JsonValue | undefined, TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
+interface DefinePollingTriggerOptions<TKey extends string, TConfig$1 extends CredentialJsonRecord, TItemJson, TState extends JsonValue | undefined, TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
   /**
    * Unique node-token-id-style key, e.g. `"msgraph-mail.on-new-mail"`.
    * Used as the persisted runtime type name — must be stable across deployments.
    */
-  readonly key: TKey$1;
+  readonly key: TKey;
   readonly title: string;
   readonly description?: string;
   /** Canvas icon (same contract as `NodeConfigBase.icon`). */
@@ -324,9 +358,9 @@ interface DefinePollingTriggerOptions<TKey$1 extends string, TConfig$1 extends C
  *
  * `poll` is also directly callable for unit-testing — no runtime needed.
  */
-interface DefinedPollingTrigger<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TItemJson, TState extends JsonValue | undefined, TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
+interface DefinedPollingTrigger<TKey extends string, TConfig$1 extends CredentialJsonRecord, TItemJson, TState extends JsonValue | undefined, TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
   readonly kind: "defined-polling-trigger";
-  readonly key: TKey$1;
+  readonly key: TKey;
   readonly title: string;
   readonly description?: string;
   /**
@@ -391,7 +425,7 @@ declare class DefinedPollingTriggerConfig<TConfig$1 extends CredentialJsonRecord
  * });
  * ```
  */
-declare function definePollingTrigger<TKey$1 extends string, TConfig$1 extends CredentialJsonRecord, TItemJson, TState extends JsonValue | undefined, TBindings extends DefinedNodeCredentialBindings | undefined = undefined>(options: DefinePollingTriggerOptions<TKey$1, TConfig$1, TItemJson, TState, TBindings>): DefinedPollingTrigger<TKey$1, TConfig$1, TItemJson, TState, TBindings>;
+declare function definePollingTrigger<TKey extends string, TConfig$1 extends CredentialJsonRecord, TItemJson, TState extends JsonValue | undefined, TBindings extends DefinedNodeCredentialBindings | undefined = undefined>(options: DefinePollingTriggerOptions<TKey, TConfig$1, TItemJson, TState, TBindings>): DefinedPollingTrigger<TKey, TConfig$1, TItemJson, TState, TBindings>;
 //#endregion
 //#region src/events/ConnectionInvocationEventPublisher.d.ts
 /**
@@ -570,8 +604,9 @@ declare class DefaultExecutionContextFactory implements ExecutionContextFactory
   private readonly costTrackingFactory;
   private readonly currentDate;
   private readonly collections?;
+  private readonly nodeResolver?;
   private readonly telemetryDecoratorFactory;
-  constructor(binaryStorage?: BinaryStorage, telemetryFactory?: ExecutionTelemetryFactory, costTrackingFactory?: CostTrackingTelemetryFactory, currentDate?: () => Date, collections?: CollectionsContext | undefined);
+  constructor(binaryStorage?: BinaryStorage, telemetryFactory?: ExecutionTelemetryFactory, costTrackingFactory?: CostTrackingTelemetryFactory, currentDate?: () => Date, collections?: CollectionsContext | undefined, nodeResolver?: NodeResolver | undefined);
   create(args: {
     runId: RunId;
     workflowId: WorkflowId;
@@ -641,15 +676,71 @@ declare class NodeOutputNormalizer {
   private applyOutput;
 }
 //#endregion
+//#region src/execution/NodeSuspensionHandler.d.ts
+/**
+ * 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.
+ */
+declare class NodeSuspensionHandler {
+  private readonly workflowExecutionRepository;
+  private readonly humanTaskStore?;
+  private readonly tokenSigner?;
+  private readonly timeoutScheduler?;
+  /** Workspace ID to stamp on HumanTaskRecord in managed mode (T7 security fix). Null in non-managed mode. */
+  private readonly workspaceId?;
+  constructor(workflowExecutionRepository: WorkflowExecutionRepository, humanTaskStore?: HumanTaskStore | undefined, tokenSigner?: HitlResumeTokenSignerSeam | undefined, timeoutScheduler?: HitlTimeoutJobSchedulerSeam | undefined, /** Workspace ID to stamp on HumanTaskRecord in managed mode (T7 security fix). Null in non-managed mode. */
+  workspaceId?: string | undefined);
+  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>;
+  /**
+   * Parse a duration string into milliseconds.
+   * Accepts ISO 8601 durations ("PT24H", "PT30M") and shorthand ("24h", "30m", "1d").
+   * Throws for unrecognised formats.
+   */
+  private parseDurationMs;
+  private hashSchema;
+  private schemaToJson;
+}
+//#endregion
 //#region src/execution/NodeExecutor.d.ts
 declare class NodeExecutor {
   private readonly nodeInstanceFactory;
   private readonly retryRunner;
+  /** Required for HITL suspension support. When omitted, `SuspensionRequest` throws upward. */
+  private readonly suspensionHandler?;
+  /** Required alongside `suspensionHandler`. */
+  private readonly loadRunState?;
   private readonly fanInMerger;
   private readonly outputNormalizer;
   private readonly itemExprResolver;
   private readonly outputBehaviorResolver;
-  constructor(nodeInstanceFactory: WorkflowNodeInstanceFactory, retryRunner: InProcessRetryRunner, itemExprResolver?: ItemExprResolver, outputBehaviorResolver?: RunnableOutputBehaviorResolver);
+  constructor(nodeInstanceFactory: WorkflowNodeInstanceFactory, retryRunner: InProcessRetryRunner, itemExprResolver?: ItemExprResolver, outputBehaviorResolver?: RunnableOutputBehaviorResolver, /** Required for HITL suspension support. When omitted, `SuspensionRequest` throws upward. */
+  suspensionHandler?: NodeSuspensionHandler | undefined, /** Required alongside `suspensionHandler`. */
+  loadRunState?: ((runId: RunId) => Promise<PersistedRunState | undefined>) | undefined);
   execute(request: NodeActivationRequest): Promise<NodeOutputs>;
   private assertRequiredCredentialsBound;
   private isCredentialError;
@@ -968,6 +1059,91 @@ interface OAuthFlowExecutor {
   }): Promise<OAuthMaterial>;
 }
 //#endregion
+//#region src/credentials/CredentialMaterialProvider.types.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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;
+}>;
+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.
+ */
+declare class IllegalMaterialSourceError extends Error {
+  readonly source: CredentialMaterialRef["source"];
+  readonly providerName: string;
+  constructor(source: CredentialMaterialRef["source"], providerName: string);
+}
+//#endregion
+//#region src/credentials/ManagedCredentialMaterialWriteError.d.ts
+/**
+ * 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`.
+ */
+declare class ManagedCredentialMaterialWriteError extends Error {
+  constructor(message?: string);
+}
+//#endregion
+//#region src/credentials/ManagedMaterialFetchError.d.ts
+/**
+ * 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.
+ */
+declare class ManagedMaterialFetchError extends Error {
+  readonly status: number;
+  readonly providerErrorBody: string;
+  constructor(status: number, providerErrorBody: string, message?: string);
+}
+//#endregion
 //#region src/orchestration/TestSuiteRunIdFactory.d.ts
 /**
  * Mints unique TestSuiteRun identifiers. Separated from {@link import("../types").RunIdFactory}
@@ -985,7 +1161,7 @@ declare class TestSuiteRunIdFactory {
 interface TestSuiteOrchestratorEngine {
   runWorkflow(wf: WorkflowDefinition, startAt: NodeId, items: Items, parent?: ParentExecutionRef, executionOptions?: RunExecutionOptions): Promise<RunResult>;
   waitForCompletion(runId: RunId): Promise<Extract<RunResult, {
-    status: "completed" | "failed";
+    status: "completed" | "failed" | "halted";
   }>>;
 }
 interface TestSuiteCaseOutcome {
@@ -1036,5 +1212,5 @@ declare class TestSuiteOrchestrator {
   private publish;
 }
 //#endregion
-export { PersistedRuntimeTypeDecoratorOptions as $, ConfigDrivenOffloadPolicy as A, DefinedNodeConfigInput as At, DefaultAsyncSleeper as B, CredentialResolverFactory as Bt, InMemoryWorkflowExecutionRepository as C, DefineCredentialOptions as Ct, HintOnlyOffloadPolicy as D, DefineNodeExecuteArgs as Dt, LocalOnlyScheduler as E, DefineBatchNodeOptions as Et, RunnableOutputBehaviorResolver as F, defineBatchNode as Ft, chatModel as G, ChildExecutionScopeFactory as H, ItemExprResolver as I, defineNode as It, tool as J, getPersistedRuntimeTypeMetadata as K, InProcessRetryRunner as L, Clock as Lt, NodeInstanceFactory as M, DefinedNodeCredentialBinding as Mt, NodeExecutor as N, DefinedNodeCredentialBindings as Nt, DefaultDrivingScheduler as O, DefineNodeOptions as Ot, NodeOutputNormalizer as P, DefinedNodeRunContext as Pt, InjectableRuntimeDecoratorComposer as Q, CatalogBackedCostTrackingTelemetryFactory as R, SystemClock as Rt, RunSummaryMapper as S, callableTool as St, InMemoryBinaryStorage as T, DefinedNodeRegistry as Tt, DefaultExecutionBinaryService as U, AsyncSleeper as V, AbortControllerFactory as Vt, UnavailableBinaryStorage as W, PersistedRuntimeTypeNameResolver as X, StackTraceCallSitePathResolver as Y, PersistedRuntimeTypeMetadataStore as Z, PollingTriggerRuntime as _, CollectionIndexDefinition as _t, TestSuiteRunResult as a, DefinePollingTriggerExecuteContext as at, EngineCompositionDeps as b, c as bt, OAuthFlowExecutor as c, DefinePollingTriggerPollResult as ct, OAuthMaterial as d, DefinedPollingTriggerConfig as dt, PersistedRuntimeTypeKind as et, WorkflowEdgePortValidator as f, definePollingTrigger as ft, PollingRunCycleResult as g, CollectionFieldDefinition as gt, PollingRunCycleArgs as h, CollectionDefinition as ht, TestSuiteOrchestratorEngine as i, ConnectionInvocationEventPublisher as it, StaticCostCatalog as j, DefinedNodeCredentialAccessors as jt, InlineDrivingScheduler as k, DefinedNode as kt, OAuthFlowStartArgs as l, DefinePollingTriggerTestItemsContext as lt, WorkflowEdgePortValidationResult as m, CollectionColumnBuilder as mt, TestSuiteCaseOutcome as n, EventPublishingWorkflowExecutionRepository as nt, TestSuiteRunIdFactory as o, DefinePollingTriggerOptions as ot, WorkflowEdgePortError as p, DefinedCollectionRegistry as pt, node as q, TestSuiteOrchestrator as r, InMemoryRunEventBus as rt, OAuthFlowCallbackArgs as s, DefinePollingTriggerPollContext as st, RunTestSuiteArgs as t, PersistedRuntimeTypeMetadata as tt, OAuthFlowStartResult as u, DefinedPollingTrigger as ut, PollingTriggerStartArgs as v, DefineCollectionOptions as vt, InMemoryRunDataFactory as w, defineCredential as wt, EngineFactory as x, defineCollection as xt, WorkflowRepositoryWebhookTriggerMatcher as y, DefinedCollection as yt, DefaultExecutionContextFactory as z, NodeEventPublisher as zt };
-//# sourceMappingURL=index-62Ba9f7D.d.ts.map
+export { getPersistedRuntimeTypeMetadata as $, NodeEventPublisher as $t, InMemoryWorkflowExecutionRepository as A, DefineCredentialOptions as At, NodeExecutor as B, InboxOnTimeoutArgs as Bt, PollingRunCycleResult as C, CollectionFieldDefinition as Ct, EngineCompositionDeps as D, c as Dt, WorkflowRepositoryWebhookTriggerMatcher as E, DefinedCollection as Et, DefaultDrivingScheduler as F, InboxChannelResolverSeam as Ft, CatalogBackedCostTrackingTelemetryFactory as G, HitlTimeoutJobSchedulerToken as Gt, RunnableOutputBehaviorResolver as H, HitlResumeTokenSignerSeam as Ht, InlineDrivingScheduler as I, InboxChannelResolverToken as It, AsyncSleeper as J, HumanTaskStatus as Jt, DefaultExecutionContextFactory as K, HitlWorkspaceIdToken as Kt, ConfigDrivenOffloadPolicy as L, InboxDeliverArgs as Lt, InMemoryBinaryStorage as M, DefinedNodeRegistry as Mt, LocalOnlyScheduler as N, ControlPlaneInboxChannelToken as Nt, EngineFactory as O, defineCollection as Ot, HintOnlyOffloadPolicy as P, InboxChannel as Pt, chatModel as Q, SystemClock as Qt, StaticCostCatalog as R, InboxDelivery as Rt, PollingRunCycleArgs as S, CollectionDefinition as St, PollingTriggerStartArgs as T, DefineCollectionOptions as Tt, ItemExprResolver as U, HitlResumeTokenSignerToken as Ut, NodeOutputNormalizer as V, LocalInboxChannelToken as Vt, InProcessRetryRunner as W, HitlTimeoutJobSchedulerSeam as Wt, DefaultExecutionBinaryService as X, HumanTaskStoreToken as Xt, ChildExecutionScopeFactory as Y, HumanTaskStore as Yt, UnavailableBinaryStorage as Z, Clock as Zt, OAuthFlowStartResult as _, DefinedPollingTrigger as _t, TestSuiteRunResult as a, InjectableRuntimeDecoratorComposer as at, WorkflowEdgePortError as b, DefinedCollectionRegistry as bt, ManagedCredentialMaterialWriteError as c, PersistedRuntimeTypeMetadata as ct, CredentialMaterialRef as d, ConnectionInvocationEventPublisher as dt, CredentialResolverFactory as en, node as et, IllegalMaterialSourceError as f, DefinePollingTriggerExecuteContext as ft, OAuthFlowStartArgs as g, DefinePollingTriggerTestItemsContext as gt, OAuthFlowExecutor as h, DefinePollingTriggerPollResult as ht, TestSuiteOrchestratorEngine as i, PersistedRuntimeTypeMetadataStore as it, InMemoryRunDataFactory as j, defineCredential as jt, RunSummaryMapper as k, callableTool as kt, CallerContext as l, EventPublishingWorkflowExecutionRepository as lt, OAuthFlowCallbackArgs as m, DefinePollingTriggerPollContext as mt, TestSuiteCaseOutcome as n, StackTraceCallSitePathResolver as nt, TestSuiteRunIdFactory as o, PersistedRuntimeTypeDecoratorOptions as ot, MaterialBundle as p, DefinePollingTriggerOptions as pt, DefaultAsyncSleeper as q, HumanTaskRecord as qt, TestSuiteOrchestrator as r, PersistedRuntimeTypeNameResolver as rt, ManagedMaterialFetchError as s, PersistedRuntimeTypeKind as st, RunTestSuiteArgs as t, AbortControllerFactory as tn, tool as tt, CredentialMaterialProvider as u, InMemoryRunEventBus as ut, OAuthMaterial as v, DefinedPollingTriggerConfig as vt, PollingTriggerRuntime as w, CollectionIndexDefinition as wt, WorkflowEdgePortValidationResult as x, CollectionColumnBuilder as xt, WorkflowEdgePortValidator as y, definePollingTrigger as yt, NodeInstanceFactory as z, InboxOnDecisionArgs as zt };
+//# sourceMappingURL=index-BZDhEQ6W.d.ts.map