@codemation/core 0.11.1 → 0.13.0

package/src/contracts/CodemationTelemetryAttributeNames.ts

@@ -19,4 +19,14 @@ export class CodemationTelemetryAttributeNames {
   static readonly mcpServerId = "mcp.server_id";
   /** MCP tool name on spans created for callTool invocations. */
   static readonly mcpToolName = "mcp.tool_name";
+  /** Terminal node-execution status (e.g. `"hitl-approved"`, `"hitl-rejected"`) on HITL outcome spans. */
+  static readonly nodeExecutionStatus = "codemation.node.execution_status";
+  /** Populated on run-halted spans; discriminates the halt reason (e.g. `"hitl-rejected"`). */
+  static readonly runHaltReason = "codemation.run.halt_reason";
+  /** Human task ID on `hitl.task.*` span events. */
+  static readonly hitlTaskId = "codemation.hitl.task_id";
+  /** HITL channel name (e.g. `"inbox"`, `"control-plane-inbox"`) on `hitl.task.*` span events. */
+  static readonly hitlChannel = "codemation.hitl.channel";
+  /** Decision outcome (e.g. `"approved"`, `"rejected"`) on `hitl.task.decided` span events. */
+  static readonly hitlDecisionStatus = "codemation.hitl.decision_status";
 }

package/src/contracts/credentialTypes.ts

@@ -162,6 +162,16 @@ export type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord
   setupStatus: CredentialSetupStatus;
   createdAt: string;
   updatedAt: string;
+  /**
+   * Pointer to where the credential material bytes live. For OSS / standalone
+   * rows this is `{source: "local", ref: instanceId}` and the bytes co-locate
+   * with the row in the workspace DB. For managed-mode rows this is
+   * `{source: "control-plane", ref: <cp_id>}` and the bytes live at CP.
+   *
+   * The seam is read through `CredentialMaterialProvider`. See
+   * `docs/design/credentials-oauth-unification.md` ("Material provider seam").
+   */
+  material: Readonly<{ source: "local" | "control-plane"; ref: string }>;
 }>;
 
 /**

package/src/contracts/hitlSeamTypes.ts

@@ -0,0 +1,34 @@
+import type { TypeToken } from "../di";
+
+/**
+ * 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.
+ */
+
+/** Signs and hashes a HITL resume token. Core only needs the sign and hash operations. */
+export 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. */
+export interface HitlTimeoutJobSchedulerSeam {
+  enqueueTimeoutJob(args: { taskId: string; expiresAt: Date }): Promise<void>;
+}
+
+export const HitlResumeTokenSignerToken = Symbol.for("codemation.core.HitlResumeTokenSigner") as TypeToken<
+  HitlResumeTokenSignerSeam | undefined
+>;
+
+export const HitlTimeoutJobSchedulerToken = Symbol.for("codemation.core.HitlTimeoutJobScheduler") as TypeToken<
+  HitlTimeoutJobSchedulerSeam | undefined
+>;
+
+/**
+ * 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.
+ */
+export const HitlWorkspaceIdToken = Symbol.for("codemation.core.HitlWorkspaceId") as TypeToken<string | undefined>;

package/src/contracts/humanTaskStoreTypes.ts

@@ -0,0 +1,48 @@
+import type { TypeToken } from "../di";
+import type { HumanTaskActor, HumanTaskSubject } from "./runtimeTypes";
+import type { JsonValue } from "./workflowTypes";
+
+export type HumanTaskStatus = "pending" | "decided" | "timed_out" | "auto_accepted" | "cancelled";
+
+/** Persisted record for a single HITL task instance. */
+export 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;
+}
+
+export 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>;
+}
+
+export const HumanTaskStoreToken = Symbol.for("codemation.core.HumanTaskStore") as TypeToken<
+  HumanTaskStore | undefined
+>;

package/src/contracts/inboxChannelTypes.ts

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

package/src/contracts/index.ts

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

package/src/contracts/runTypes.ts

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

package/src/contracts/runtimeTypes.ts

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

package/src/contracts/workspaceFileTypes.ts

@@ -0,0 +1,73 @@
+import type { TypeToken } from "../di";
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export class WorkspaceFileNotFoundError extends Error {
+  constructor(readonly key: string) {
+    super(`Workspace file not found: ${key}`);
+    this.name = "WorkspaceFileNotFoundError";
+  }
+}
+
+/**
+ * DI token for the workspace-scoped file storage adapter.
+ * Registered by `@codemation/host`; resolved by workspace-file nodes via `ctx.resolve(...)`.
+ */
+export const WorkspaceFileStorageToken = Symbol.for("codemation.core.WorkspaceFileStorage") as TypeToken<
+  IWorkspaceFileStorage | undefined
+>;

package/src/credentials/CredentialMaterialProvider.types.ts

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

package/src/credentials/ManagedCredentialMaterialWriteError.ts

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

package/src/credentials/ManagedMaterialFetchError.ts

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

package/src/execution/ActivationEnqueueService.ts

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