@codemation/core 0.11.1 → 0.13.0

package/dist/{index-62Ba9f7D.d.ts → index-CqZeNGAp.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 { $t as PersistedRunState, A as DefinedNodeCredentialAccessors, Ai as NodeActivationContinuation, Ar as RunId, Bi as NodeExecutionStatePublisher, Ci as HumanTaskActor, Do as OutputPortKey, Dr as PersistedRunPolicySnapshot, Ei as HumanTaskSubject, Eo as NodeId, Er as ParentExecutionRef, Fi as NodeBinaryAttachmentService, Fr as TriggerNodeConfig, Gi as PreparedNodeActivationDispatch, Gn as RunEventSubscription, Ha as CostTrackingTelemetry, Hi as NodeResolver, Ii as NodeExecutionContext, Ja as CollectionsContext, Jn as TestSuiteRunId, Ka as CostTrackingUsageRecord, Kn as TestCaseRunStatus, Li as NodeExecutionRequest, M as DefinedNodeCredentialBindings, Mi as NodeActivationRequest, Mr as RunnableNodeConfig, O as DefinedNode, Oa as TelemetryScope, On as TypeToken, Or as RunDataFactory, Pi as NodeActivationScheduler, Qn as BinaryAttachment, Qt as PersistedRunSchedulingState, Rt as ConnectionInvocationId, Si as ExecutionContextFactory, So as PollingTriggerLogger, Sr as NodeOutputs, Un as RunEvent, Vn as EngineExecutionLimitsPolicy, Vt as EngineRunCounters, Wa as CostTrackingTelemetryFactory, Wn as RunEventBus, Wt as NodeExecutionSnapshot, Yi as SuspensionRequest, Zn as ActivationIdFactory, _i as EngineDeps, _n as RunTestContext, aa as WorkflowRepository, ba as ExecutionTelemetryFactory, bi as ExecutionBinaryService, bn as WorkflowExecutionPruneRepository, cn as RunExecutionOptions, da as TriggerInstanceId, di as BinaryStorage, dr as NodeActivationId, eo as CredentialFieldSchema, er as Edge, fi as BinaryStorageReadResult, fn as RunResult, fo as CredentialSessionFactoryArgs, fr as NodeConfigBase, ga as WebhookTriggerRoutingDiagnostics, gn as RunSummary, go as CredentialTypeDefinition, hi as BinaryStorageWriteResult, ho as CredentialType, ht as CostCatalogEntry, ia as WorkflowNodeInstanceFactory, ir as Items, ja as TelemetrySpanScope, ko as WorkflowId, kr as RunDataSnapshot, lr as JsonValue, ma as WebhookTriggerMatcher, mt as CostCatalog, na as TriggerSetupStateRepository, nn as PersistedWorkflowSnapshotNode, nr as Item, oo as CredentialJsonRecord, pa as WebhookInvocationMatch, pi as BinaryStorageStatResult, po as CredentialSessionService, pr as NodeDefinition, qn as TestSuiteRunStatus, ra as TriggerTestItemsContext, si as RetryPolicySpec, to as CredentialHealth, tr as ExecutionMode, ua as HttpMethod, ui as BinaryBody, un as RunPruneCandidate, uo as CredentialRequirement, ur as MutableRunData, va as WorkflowActivationPolicy, vr as NodeInspectorSummaryRow, wi as HumanTaskHandle, wr as NodeSchedulerDecision, xi as ExecutionContext, xn as WorkflowExecutionRepository, xr as NodeOffloadPolicy, ya as ExecutionTelemetry, yn as WorkflowExecutionListingRepository, zi as NodeExecutionScheduler, zr as WorkflowDefinition, zt as ConnectionInvocationRecord } from "./index-rllWL4r-.js";
+import { i as WorkflowSnapshotCodec, u as Engine } from "./RunIntentService-DYpqfu6D.js";
+import { B as ZodSchemaAny, K as CallableToolConfig, q as CallableToolConfigOptions } from "./ItemsInputNormalizer-BWtlwdVI.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
 /**
@@ -525,6 +559,9 @@ declare class DefaultExecutionBinaryService implements ExecutionBinaryService {
     activationId: NodeActivationId;
   }): NodeBinaryAttachmentService;
   openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+  getBytes(attachment: BinaryAttachment, maxBytes?: number): Promise<Uint8Array>;
+  getText(attachment: BinaryAttachment, maxBytes?: number): Promise<string>;
+  getJson<T = unknown>(attachment: BinaryAttachment, maxBytes?: number): Promise<T>;
 }
 //#endregion
 //#region src/execution/ChildExecutionScopeFactory.d.ts
@@ -570,8 +607,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 +679,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 +1062,154 @@ 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/contracts/workspaceFileTypes.d.ts
+/**
+ * Metadata returned for a workspace file object.
+ * Filename and contentType come from the S3 object's custom metadata
+ * (stamped by the control plane at upload time — story 03).
+ * The local-fs driver reads them from a companion .meta.json sidecar.
+ */
+interface WorkspaceFileMetadata {
+  /** Storage key: `<workspaceId>/files/<fileId>` */
+  readonly key: string;
+  /** Last path segment of the storage key. */
+  readonly fileId: string;
+  /** Original filename as stamped by the CP at upload time. Empty string if not yet stamped (pre-story-03). */
+  readonly filename: string;
+  readonly contentType: string;
+  readonly size: number;
+  readonly lastModified: Date;
+}
+/**
+ * Read-only, workspace-scoped port for accessing the shared workspace file pool.
+ * Implemented in `@codemation/host`; nodes reach it via `ctx.resolve(WorkspaceFileStorageToken)`.
+ *
+ * Key scheme: `<workspaceId>/files/<fileId>` — but nodes never construct raw keys.
+ * Use the workspace-level helpers (`listFiles`, `getFileByName`, `getFileById`) instead.
+ *
+ * This adapter is SEPARATE from the run-scoped BinaryStorage — do not confuse the two.
+ */
+interface IWorkspaceFileStorage {
+  /**
+   * Lists all files in this workspace, sorted newest-first by lastModified.
+   * Optional case-insensitive substring filter on filename.
+   */
+  listFiles(filenameFilter?: string): Promise<ReadonlyArray<WorkspaceFileMetadata>>;
+  /**
+   * Returns metadata for the newest file with the given filename in this workspace.
+   * @throws WorkspaceFileNotFoundError when no file with that name exists.
+   */
+  getFileByName(filename: string): Promise<WorkspaceFileMetadata>;
+  /**
+   * Returns metadata for the file with the given fileId in this workspace.
+   * @throws WorkspaceFileNotFoundError when no file with that id exists.
+   */
+  getFileById(fileId: string): Promise<WorkspaceFileMetadata>;
+  /**
+   * Returns a non-buffered stream of the stored object's bytes.
+   * Accepts a full storage key or a fileId (prefixes as needed).
+   * @throws WorkspaceFileNotFoundError when the key does not exist.
+   */
+  getStream(key: string): Promise<ReadableStream<Uint8Array>>;
+}
+/**
+ * Error thrown when a requested workspace file key does not exist.
+ */
+declare class WorkspaceFileNotFoundError extends Error {
+  readonly key: string;
+  constructor(key: string);
+}
+/**
+ * DI token for the workspace-scoped file storage adapter.
+ * Registered by `@codemation/host`; resolved by workspace-file nodes via `ctx.resolve(...)`.
+ */
+declare const WorkspaceFileStorageToken: TypeToken<IWorkspaceFileStorage | undefined>;
+//#endregion
 //#region src/orchestration/TestSuiteRunIdFactory.d.ts
 /**
  * Mints unique TestSuiteRun identifiers. Separated from {@link import("../types").RunIdFactory}
@@ -985,7 +1227,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 +1278,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 { ChildExecutionScopeFactory as $, HumanTaskStore as $t, WorkflowRepositoryWebhookTriggerMatcher as A, DefinedCollection as At, InlineDrivingScheduler as B, InboxChannelResolverToken as Bt, WorkflowEdgePortValidator as C, definePollingTrigger as Ct, PollingRunCycleResult as D, CollectionFieldDefinition as Dt, PollingRunCycleArgs as E, CollectionDefinition as Et, InMemoryRunDataFactory as F, defineCredential as Ft, NodeOutputNormalizer as G, LocalInboxChannelToken as Gt, StaticCostCatalog as H, InboxDelivery as Ht, InMemoryBinaryStorage as I, DefinedNodeRegistry as It, InProcessRetryRunner as J, HitlTimeoutJobSchedulerSeam as Jt, RunnableOutputBehaviorResolver as K, HitlResumeTokenSignerSeam as Kt, LocalOnlyScheduler as L, ControlPlaneInboxChannelToken as Lt, EngineFactory as M, defineCollection as Mt, RunSummaryMapper as N, callableTool as Nt, PollingTriggerRuntime as O, CollectionIndexDefinition as Ot, InMemoryWorkflowExecutionRepository as P, DefineCredentialOptions as Pt, AsyncSleeper as Q, HumanTaskStatus as Qt, HintOnlyOffloadPolicy as R, InboxChannel as Rt, OAuthMaterial as S, DefinedPollingTriggerConfig as St, WorkflowEdgePortValidationResult as T, CollectionColumnBuilder as Tt, NodeInstanceFactory as U, InboxOnDecisionArgs as Ut, ConfigDrivenOffloadPolicy as V, InboxDeliverArgs as Vt, NodeExecutor as W, InboxOnTimeoutArgs as Wt, DefaultExecutionContextFactory as X, HitlWorkspaceIdToken as Xt, CatalogBackedCostTrackingTelemetryFactory as Y, HitlTimeoutJobSchedulerToken as Yt, DefaultAsyncSleeper as Z, HumanTaskRecord as Zt, MaterialBundle as _, DefinePollingTriggerOptions as _t, TestSuiteRunResult as a, AbortControllerFactory as an, tool as at, OAuthFlowStartArgs as b, DefinePollingTriggerTestItemsContext as bt, WorkspaceFileMetadata as c, PersistedRuntimeTypeMetadataStore as ct, ManagedMaterialFetchError as d, PersistedRuntimeTypeKind as dt, HumanTaskStoreToken as en, DefaultExecutionBinaryService as et, ManagedCredentialMaterialWriteError as f, PersistedRuntimeTypeMetadata as ft, IllegalMaterialSourceError as g, DefinePollingTriggerExecuteContext as gt, CredentialMaterialRef as h, ConnectionInvocationEventPublisher as ht, TestSuiteOrchestratorEngine as i, CredentialResolverFactory as in, node as it, EngineCompositionDeps as j, c as jt, PollingTriggerStartArgs as k, DefineCollectionOptions as kt, WorkspaceFileNotFoundError as l, InjectableRuntimeDecoratorComposer as lt, CredentialMaterialProvider as m, InMemoryRunEventBus as mt, TestSuiteCaseOutcome as n, SystemClock as nn, chatModel as nt, TestSuiteRunIdFactory as o, StackTraceCallSitePathResolver as ot, CallerContext as p, EventPublishingWorkflowExecutionRepository as pt, ItemExprResolver as q, HitlResumeTokenSignerToken as qt, TestSuiteOrchestrator as r, NodeEventPublisher as rn, getPersistedRuntimeTypeMetadata as rt, IWorkspaceFileStorage as s, PersistedRuntimeTypeNameResolver as st, RunTestSuiteArgs as t, Clock as tn, UnavailableBinaryStorage as tt, WorkspaceFileStorageToken as u, PersistedRuntimeTypeDecoratorOptions as ut, OAuthFlowCallbackArgs as v, DefinePollingTriggerPollContext as vt, WorkflowEdgePortError as w, DefinedCollectionRegistry as wt, OAuthFlowStartResult as x, DefinedPollingTrigger as xt, OAuthFlowExecutor as y, DefinePollingTriggerPollResult as yt, DefaultDrivingScheduler as z, InboxChannelResolverSeam as zt };
+//# sourceMappingURL=index-CqZeNGAp.d.ts.map