@codemation/core-nodes 0.8.1 → 0.10.0

package/dist/index.cjs

@@ -1309,6 +1309,7 @@ const string$1 = (params) => {
 };
 const integer = /^-?\d+$/;
 const number$1 = /^-?\d+(?:\.\d+)?$/;
+const boolean$1 = /^(?:true|false)$/i;
 const lowercase = /^[^A-Z]*$/;
 const uppercase = /^[^a-z]*$/;
 
@@ -2087,6 +2088,24 @@ const $ZodNumberFormat = /* @__PURE__ */ $constructor("$ZodNumberFormat", (inst,
 	$ZodCheckNumberFormat.init(inst, def);
 	$ZodNumber.init(inst, def);
 });
+const $ZodBoolean = /* @__PURE__ */ $constructor("$ZodBoolean", (inst, def) => {
+	$ZodType.init(inst, def);
+	inst._zod.pattern = boolean$1;
+	inst._zod.parse = (payload, _ctx) => {
+		if (def.coerce) try {
+			payload.value = Boolean(payload.value);
+		} catch (_) {}
+		const input = payload.value;
+		if (typeof input === "boolean") return payload;
+		payload.issues.push({
+			expected: "boolean",
+			code: "invalid_type",
+			input,
+			inst
+		});
+		return payload;
+	};
+});
 const $ZodUnknown = /* @__PURE__ */ $constructor("$ZodUnknown", (inst, def) => {
 	$ZodType.init(inst, def);
 	inst._zod.parse = (payload) => payload;
@@ -3163,6 +3182,13 @@ function _int(Class, params) {
 	});
 }
 /* @__NO_SIDE_EFFECTS__ */
+function _boolean(Class, params) {
+	return new Class({
+		type: "boolean",
+		...normalizeParams(params)
+	});
+}
+/* @__NO_SIDE_EFFECTS__ */
 function _unknown(Class) {
 	return new Class({ type: "unknown" });
 }
@@ -3329,6 +3355,17 @@ function _array(Class, element, params) {
 	});
 }
 /* @__NO_SIDE_EFFECTS__ */
+function _custom(Class, fn, _params) {
+	const norm = normalizeParams(_params);
+	norm.abort ?? (norm.abort = true);
+	return new Class({
+		type: "custom",
+		check: "custom",
+		fn,
+		...norm
+	});
+}
+/* @__NO_SIDE_EFFECTS__ */
 function _refine(Class, fn, _params) {
 	return new Class({
 		type: "custom",
@@ -4352,6 +4389,59 @@ var OpenAiChatModelPresets = class {
 };
 const openAiChatModelPresets = new OpenAiChatModelPresets();
 
+//#endregion
+//#region src/chatModels/ManagedHmacSignerFactory.types.ts
+/**
+* Creates an HMAC-signing fetch wrapper that authenticates requests to
+* Codemation managed services (LLM broker, doc-scanner) with the
+* Codemation-Hmac v=1 scheme.
+*
+* Mirrors HmacRequestSigner from @codemation/host/pairing without importing
+* that package (which would create a circular dependency since @codemation/host
+* depends on @codemation/core-nodes).
+*
+* @param workspaceId   - Workspace identifier injected by the CP provisioner.
+* @param pairingSecret - Base64-encoded 32-byte HMAC key injected by the provisioner.
+* @param options       - Optional behaviour flags and test seams.
+*/
+function managedHmacFetchFactory(workspaceId, pairingSecret, options) {
+	const signBody = options?.signBody ?? true;
+	return async (input, init) => {
+		const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+		const method = init?.method ?? "POST";
+		let bodyForSigning = "";
+		if (signBody && init?.body !== void 0 && init.body !== null) bodyForSigning = typeof init.body === "string" ? init.body : await new Response(init.body).text();
+		const authHeader = buildHmacAuthHeader(workspaceId, pairingSecret, method, url, bodyForSigning, options);
+		const headers = new Headers(init?.headers);
+		headers.set("Authorization", authHeader);
+		const outgoingBody = signBody ? bodyForSigning || init?.body : init?.body;
+		return fetch(input, {
+			...init,
+			body: outgoingBody,
+			headers
+		});
+	};
+}
+/**
+* Produces a Codemation-Hmac v=1 Authorization header value.
+* Algorithm must match HmacVerifier.computeSignature() in the control-plane.
+*/
+function buildHmacAuthHeader(workspaceId, pairingSecret, method, url, body, overrides) {
+	const ts = overrides?.now ? overrides.now() : Math.floor(Date.now() / 1e3);
+	const nonce = overrides?.nonce ? overrides.nonce() : (0, node_crypto.randomBytes)(16).toString("base64");
+	const parsed = new URL(url);
+	const path = (parsed.pathname + parsed.search).toLowerCase();
+	const bodyHash = (0, node_crypto.createHash)("sha256").update(body, "utf8").digest("hex");
+	const baseString = [
+		method.toUpperCase(),
+		path,
+		ts,
+		nonce,
+		bodyHash
+	].join("\n");
+	return `Codemation-Hmac v=1,workspaceId=${workspaceId},ts=${ts},nonce=${nonce},sig=${(0, node_crypto.createHmac)("sha256", Buffer.from(pairingSecret, "base64")).update(baseString, "utf8").digest("base64")}`;
+}
+
 //#endregion
 //#region src/chatModels/CodemationChatModelFactory.ts
 let CodemationChatModelFactory = class CodemationChatModelFactory$1 {
@@ -4361,7 +4451,7 @@ let CodemationChatModelFactory = class CodemationChatModelFactory$1 {
 		const workspaceId = process.env["WORKSPACE_ID"];
 		const pairingSecret = process.env["WORKSPACE_PAIRING_SECRET"];
 		if (!workspaceId || !pairingSecret) throw new Error("Codemation managed AI not available in this environment (workspace pairing is not configured).");
-		const hmacFetch = this.buildHmacSignedFetch(workspaceId, pairingSecret);
+		const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret);
 		const languageModel = (0, __ai_sdk_openai.createOpenAI)({
 			baseURL: `${gatewayUrl}/v1`,
 			apiKey: "codemation-managed",
@@ -4377,52 +4467,6 @@ let CodemationChatModelFactory = class CodemationChatModelFactory$1 {
 			}
 		});
 	}
-	/**
-	* Creates an HMAC-signed fetch wrapper for use with AI SDK's createOpenAI.
-	* Each call signs the request body with the workspace pairing secret so the
-	* LLM broker can authenticate the workspace without a user-managed API key.
-	*
-	* Mirrors HmacRequestSigner from @codemation/host/pairing without importing
-	* that package (which would create a circular dependency since @codemation/host
-	* depends on @codemation/core-nodes).
-	*/
-	buildHmacSignedFetch(workspaceId, pairingSecret) {
-		return async (input, init) => {
-			const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-			const method = init?.method ?? "POST";
-			let bodyString = "";
-			if (init?.body !== void 0 && init.body !== null) if (typeof init.body === "string") bodyString = init.body;
-			else bodyString = await new Response(init.body).text();
-			const authHeader = this.buildHmacAuthHeader(workspaceId, pairingSecret, method, url, bodyString);
-			const headers = new Headers(init?.headers);
-			headers.set("Authorization", authHeader);
-			const effectiveBody = bodyString || init?.body;
-			return fetch(input, {
-				...init,
-				body: effectiveBody,
-				headers
-			});
-		};
-	}
-	/**
-	* Produces a Codemation-Hmac v1 Authorization header value.
-	* The algorithm must match HmacVerifier.computeSignature() in the control-plane.
-	*/
-	buildHmacAuthHeader(workspaceId, pairingSecret, method, url, body) {
-		const ts = Math.floor(Date.now() / 1e3);
-		const nonce = (0, node_crypto.randomBytes)(16).toString("base64");
-		const parsed = new URL(url);
-		const path = (parsed.pathname + parsed.search).toLowerCase();
-		const bodyHash = (0, node_crypto.createHash)("sha256").update(body, "utf8").digest("hex");
-		const baseString = [
-			method.toUpperCase(),
-			path,
-			ts,
-			nonce,
-			bodyHash
-		].join("\n");
-		return `Codemation-Hmac v=1,workspaceId=${workspaceId},ts=${ts},nonce=${nonce},sig=${(0, node_crypto.createHmac)("sha256", Buffer.from(pairingSecret, "base64")).update(baseString, "utf8").digest("base64")}`;
-	}
 };
 CodemationChatModelFactory = __decorate([(0, __codemation_core.chatModel)({ packageName: "@codemation/core-nodes" })], CodemationChatModelFactory);
 
@@ -4925,6 +4969,14 @@ const ZodNumberFormat = /* @__PURE__ */ $constructor("ZodNumberFormat", (inst, d
 function int(params) {
 	return _int(ZodNumberFormat, params);
 }
+const ZodBoolean = /* @__PURE__ */ $constructor("ZodBoolean", (inst, def) => {
+	$ZodBoolean.init(inst, def);
+	ZodType.init(inst, def);
+	inst._zod.processJSONSchema = (ctx, json, params) => booleanProcessor(inst, ctx, json, params);
+});
+function boolean(params) {
+	return _boolean(ZodBoolean, params);
+}
 const ZodUnknown = /* @__PURE__ */ $constructor("ZodUnknown", (inst, def) => {
 	$ZodUnknown.init(inst, def);
 	ZodType.init(inst, def);
@@ -5236,6 +5288,9 @@ const ZodCustom = /* @__PURE__ */ $constructor("ZodCustom", (inst, def) => {
 	ZodType.init(inst, def);
 	inst._zod.processJSONSchema = (ctx, json, params) => customProcessor(inst, ctx, json, params);
 });
+function custom(fn, _params) {
+	return _custom(ZodCustom, fn ?? (() => true), _params);
+}
 function refine(fn, _params = {}) {
 	return _refine(ZodCustom, fn, _params);
 }
@@ -5485,12 +5540,22 @@ let AgentToolExecutionCoordinator = class AgentToolExecutionCoordinator$1 {
 		this.repairPolicy = repairPolicy;
 	}
 	async execute(args) {
+		if (args.plannedToolCalls.filter((c) => c.binding.humanApproval !== void 0).length > 0 && args.plannedToolCalls.length > 1) return args.plannedToolCalls.map((c) => ({
+			toolName: c.binding.config.name,
+			toolCallId: c.toolCall.id ?? c.binding.config.name,
+			result: { error: c.binding.humanApproval !== void 0 ? `HITL tool '${c.binding.config.name}' cannot be called alongside other tools in the same turn; call it alone.` : `deferred: a HITL tool in the same turn blocked execution. Retry this tool alone in the next turn.` },
+			serialized: JSON.stringify({ error: c.binding.humanApproval !== void 0 ? `HITL tool '${c.binding.config.name}' cannot be called alongside other tools in the same turn; call it alone.` : `deferred: a HITL tool in the same turn blocked execution. Retry this tool alone in the next turn.` })
+		}));
 		const results = await Promise.allSettled(args.plannedToolCalls.map(async (plannedToolCall) => await this.executePlannedToolCall({
 			...args,
 			plannedToolCall
 		})));
 		const rejected = results.find((result) => result.status === "rejected");
-		if (rejected?.status === "rejected") throw rejected.reason instanceof Error ? rejected.reason : new Error(String(rejected.reason));
+		if (rejected?.status === "rejected") {
+			const reason = rejected.reason;
+			if (reason instanceof __codemation_core.SuspensionRequest) throw reason;
+			throw reason instanceof Error ? reason : new Error(String(reason));
+		}
 		return results.filter((result) => result.status === "fulfilled").map((result) => result.value);
 	}
 	async executePlannedToolCall(args) {
@@ -5575,6 +5640,34 @@ let AgentToolExecutionCoordinator = class AgentToolExecutionCoordinator$1 {
 				result
 			};
 		} catch (error) {
+			if (error instanceof __codemation_core.SuspensionRequest) {
+				const pendingToolCallId = plannedToolCall.toolCall.id ?? plannedToolCall.binding.config.name;
+				const checkpoint = {
+					conversation: args.conversationSnapshot ? [...args.conversationSnapshot] : [],
+					turnCount: args.turnCount ?? 0,
+					toolCallCount: args.toolCallCount ?? 0,
+					pendingToolCallId,
+					agentName: args.agentName,
+					modelId: args.modelId ?? ""
+				};
+				const agentReasoning = this.extractLastAssistantText(args.conversationSnapshot ?? []);
+				const augmented = new __codemation_core.SuspensionRequest({
+					...error.request,
+					metadata: {
+						...error.request.metadata,
+						agentCheckpoint: checkpoint,
+						pendingToolCallId,
+						agentReasoning,
+						onRejected: plannedToolCall.binding.humanApproval?.onRejected ?? "return"
+					}
+				});
+				await span.end({
+					status: "error",
+					statusMessage: "suspended",
+					endedAt: /* @__PURE__ */ new Date()
+				});
+				throw augmented;
+			}
 			const classification = this.errorClassifier.classify({
 				error,
 				toolName: plannedToolCall.binding.config.name,
@@ -5750,6 +5843,24 @@ let AgentToolExecutionCoordinator = class AgentToolExecutionCoordinator$1 {
 	extractErrorDetails(error) {
 		return error.details;
 	}
+	/**
+	* Extracts the text content from the last assistant message in the conversation snapshot.
+	* Used to populate `agentReasoning` in the HITL suspension metadata.
+	*/
+	extractLastAssistantText(conversation) {
+		for (let i = conversation.length - 1; i >= 0; i--) {
+			const msg = conversation[i];
+			if (msg?.role !== "assistant") continue;
+			const content = msg.content;
+			if (typeof content === "string") return content;
+			if (Array.isArray(content)) {
+				const textParts = content.filter((part) => typeof part === "object" && part.type === "text").map((part) => part.text);
+				if (textParts.length > 0) return textParts.join("");
+			}
+			break;
+		}
+		return "";
+	}
 	serializeIssue(issue$1) {
 		const result = {
 			path: [...issue$1.path],
@@ -6103,6 +6214,7 @@ var AgentItemPortMap = class {
 //#endregion
 //#region src/nodes/AIAgentNode.ts
 var _ref, _ref2, _ref3, _ref4, _ref5;
+const HITL_SOLO_CONSTRAINT_SENTENCE = "This tool requires human approval and may take time. Call it alone — do not invoke other tools in the same turn. Your turn will be paused until a decision is made.";
 let AIAgentNode = class AIAgentNode$1 {
 	kind = "node";
 	outputPorts = ["main"];
@@ -6120,13 +6232,90 @@ let AIAgentNode = class AIAgentNode$1 {
 		this.connectionCredentialExecutionContextFactory = this.executionHelpers.createConnectionCredentialExecutionContextFactory(credentialSessions);
 	}
 	async execute(args) {
-		const prepared = await this.getOrPrepareExecution(args.ctx);
+		const { ctx } = args;
+		if (ctx.resumeContext) return this.executeResumed(args, ctx.resumeContext);
+		const prepared = await this.getOrPrepareExecution(ctx);
 		const itemWithMappedJson = {
 			...args.item,
 			json: args.input
 		};
 		return (await this.runAgentForItem(prepared, itemWithMappedJson, args.itemIndex, args.items)).json;
 	}
+	/**
+	* Resume path: re-enters the agent loop after a HITL suspension.
+	* Reconstructs the conversation from the checkpoint, injects the human decision
+	* as a tool_result, and continues the loop from where it suspended.
+	*/
+	async executeResumed(args, resumeContext) {
+		const { ctx } = args;
+		const taskMetadata = resumeContext.task.metadata ?? {};
+		const checkpoint = taskMetadata["agentCheckpoint"];
+		const onRejected = taskMetadata["onRejected"] ?? "return";
+		if (!checkpoint) {
+			const prepared$1 = await this.getOrPrepareExecution(ctx);
+			const itemWithMappedJson = {
+				...args.item,
+				json: args.input
+			};
+			return (await this.runAgentForItem(prepared$1, itemWithMappedJson, args.itemIndex, args.items)).json;
+		}
+		if (resumeContext.decision.kind === "decided" && resumeContext.decision.value === null && onRejected === "halt") return;
+		const decision = this.normalizeDecision(resumeContext);
+		if (decision.status === "rejected" && onRejected === "halt") return;
+		const prepared = await this.getOrPrepareExecution(ctx);
+		const item = args.item;
+		const itemInputsByPort = AgentItemPortMap.fromItem(item);
+		const itemScopedTools = this.createItemScopedTools(prepared.resolvedTools, ctx, item, args.itemIndex, args.items);
+		const toolResultEntry = {
+			toolName: checkpoint.pendingToolCallId,
+			toolCallId: checkpoint.pendingToolCallId,
+			result: decision,
+			serialized: JSON.stringify(decision)
+		};
+		const conversation = [...checkpoint.conversation, AgentMessageFactory.createToolResultsMessage([toolResultEntry])];
+		const loopResult = await this.runTurnLoopUntilFinalAnswer({
+			prepared,
+			itemInputsByPort,
+			itemScopedTools,
+			conversation,
+			resumedTurnCount: checkpoint.turnCount,
+			resumedToolCallCount: checkpoint.toolCallCount
+		});
+		await ctx.telemetry.recordMetric({
+			name: __codemation_core.CodemationTelemetryMetricNames.agentTurns,
+			value: loopResult.turnCount
+		});
+		await ctx.telemetry.recordMetric({
+			name: __codemation_core.CodemationTelemetryMetricNames.agentToolCalls,
+			value: loopResult.toolCallCount
+		});
+		const outputJson = await this.resolveFinalOutputJson(prepared, itemInputsByPort, conversation, loopResult.finalText, itemScopedTools.length > 0);
+		return this.buildOutputItem(item, outputJson).json;
+	}
+	/**
+	* Normalizes a {@link ResumeContext} decision into a flat JSON-serializable shape
+	* suitable for injection as a tool_result content.
+	*/
+	normalizeDecision(resumeContext) {
+		const { decision } = resumeContext;
+		if (decision.kind === "decided") {
+			const value = decision.value;
+			return {
+				status: (typeof value === "object" && value !== null && "approved" in value ? Boolean(value["approved"]) : true) ? "approved" : "rejected",
+				value: decision.value,
+				actor: decision.actor,
+				decidedAt: decision.decidedAt.toISOString()
+			};
+		}
+		if (decision.kind === "timed_out") return {
+			status: "timed_out",
+			at: decision.at.toISOString()
+		};
+		return {
+			status: "auto_accepted",
+			at: decision.at.toISOString()
+		};
+	}
 	async getOrPrepareExecution(ctx) {
 		let pending = this.preparedByExecutionContext.get(ctx);
 		if (!pending) {
@@ -6247,7 +6436,7 @@ let AIAgentNode = class AIAgentNode$1 {
 		const { prepared, itemInputsByPort, itemScopedTools, conversation } = args;
 		const { ctx, guardrails, toolLoadingStrategy } = prepared;
 		let finalText = "";
-		let toolCallCount = 0;
+		let toolCallCount = args.resumedToolCallCount ?? 0;
 		let turnCount = 0;
 		const repairAttemptsByToolName = /* @__PURE__ */ new Map();
 		/** Tool IDs surfaced by find_tools across all prior turns in this item run. */
@@ -6288,11 +6477,17 @@ let AIAgentNode = class AIAgentNode$1 {
 				const plannedToolCalls = this.planToolCalls(itemScopedTools, coordinatorCalls, ctx.nodeId);
 				toolCallCount += plannedToolCalls.length;
 				await this.markQueuedTools(plannedToolCalls, ctx);
+				const assistantMsg = result.assistantMessage ?? AgentMessageFactory.createAssistantWithToolCalls(result.text, result.toolCalls);
+				const conversationWithAssistant = [...conversation, assistantMsg];
 				const executed = await this.toolExecutionCoordinator.execute({
 					plannedToolCalls,
 					ctx,
 					agentName: this.getAgentDisplayName(ctx),
-					repairAttemptsByToolName
+					repairAttemptsByToolName,
+					conversationSnapshot: conversationWithAssistant,
+					turnCount,
+					toolCallCount,
+					modelId: this.resolveChatModelName(ctx.config.chatModel)
 				});
 				coordinatorExecutedCalls.push(...executed);
 			}
@@ -6354,6 +6549,7 @@ let AIAgentNode = class AIAgentNode$1 {
 				connectionNodeId: __codemation_core.ConnectionNodeIdFactory.toolConnectionNodeId(ctx.nodeId, entry.config.name),
 				getCredentialRequirements: () => entry.config.getCredentialRequirements?.() ?? []
 			});
+			const hitlBehavior = this.resolveHumanApprovalBehavior(entry.config);
 			return {
 				config: entry.config,
 				inputSchema: entry.runtime.inputSchema,
@@ -6368,11 +6564,22 @@ let AIAgentNode = class AIAgentNode$1 {
 						items,
 						hooks
 					});
-				}
+				},
+				...hitlBehavior !== void 0 ? { humanApproval: hitlBehavior } : {}
 			};
 		});
 	}
 	/**
+	* Detects whether a tool config is backed by a `defineHumanApprovalNode` marker
+	* and returns the HITL behavior config, or `undefined` when not a HITL tool.
+	*/
+	resolveHumanApprovalBehavior(config$1) {
+		if (!this.isNodeBackedToolConfig(config$1)) return void 0;
+		const marker = config$1.node.humanApprovalToolBehavior;
+		if (marker === void 0) return void 0;
+		return { onRejected: marker.onRejected ?? "return" };
+	}
+	/**
 	* Invoke a text turn using the merged tool set from item-scoped tools (coordinator-managed)
 	* and strategy tools (find_tools + discovered MCP tools).
 	* Strategy tools take precedence for names that overlap.
@@ -6402,6 +6609,8 @@ let AIAgentNode = class AIAgentNode$1 {
 	/**
 	* Builds a ToolSet from resolved tools for strategy initialization.
 	* The strategy uses this for its "always-included" node-backed tool descriptions.
+	* HITL tools (detected via the `humanApprovalToolBehavior` field set by `defineHumanApprovalNode`) get the solo-constraint sentence
+	* appended to their description.
 	*/
 	buildToolSetFromResolved(resolvedTools) {
 		if (resolvedTools.length === 0) return {};
@@ -6411,8 +6620,10 @@ let AIAgentNode = class AIAgentNode$1 {
 				schemaName: entry.config.name,
 				requireObjectRoot: true
 			});
+			const baseDescription = entry.config.description ?? entry.runtime.defaultDescription;
+			const description = this.resolveHumanApprovalBehavior(entry.config) !== void 0 ? `${baseDescription} ${HITL_SOLO_CONSTRAINT_SENTENCE}` : baseDescription;
 			toolSet[entry.config.name] = {
-				description: entry.config.description ?? entry.runtime.defaultDescription,
+				description,
 				inputSchema: (0, ai.jsonSchema)(schemaRecord)
 			};
 		}
@@ -6440,8 +6651,10 @@ let AIAgentNode = class AIAgentNode$1 {
 				schemaName: entry.config.name,
 				requireObjectRoot: true
 			});
+			const baseDescription = entry.config.description;
+			const description = entry.humanApproval !== void 0 && baseDescription !== void 0 ? `${baseDescription} ${HITL_SOLO_CONSTRAINT_SENTENCE}` : entry.humanApproval !== void 0 ? HITL_SOLO_CONSTRAINT_SENTENCE : baseDescription;
 			toolSet[entry.config.name] = {
-				description: entry.config.description,
+				description,
 				inputSchema: (0, ai.jsonSchema)(schemaRecord)
 			};
 		}
@@ -6609,7 +6822,11 @@ let AIAgentNode = class AIAgentNode$1 {
 		});
 		try {
 			const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
-			const outputSchema = structuredOptions?.strict && !this.isZodSchema(schema) ? ai.Output.object({ schema: (0, ai.jsonSchema)(schema) }) : ai.Output.object({ schema });
+			const schemaRecord = this.isZodSchema(schema) ? this.executionHelpers.createJsonSchemaRecord(schema, {
+				schemaName: structuredOptions?.schemaName ?? "structured_output",
+				requireObjectRoot: true
+			}) : schema;
+			const outputSchema = ai.Output.object({ schema: (0, ai.jsonSchema)(schemaRecord) });
 			const result = await (0, ai.generateText)({
 				model: model.languageModel,
 				messages: [...messages],
@@ -8758,6 +8975,173 @@ const collectionDeleteNode = (0, __codemation_core.defineNode)({
 	}
 });
 
+//#endregion
+//#region src/nodes/InboxApprovalNode.types.ts
+function resolveSubjectField(field, item) {
+	return typeof field === "function" ? field({ item }) : field;
+}
+/**
+* Auto-detecting inbox approval node.
+*
+* Uses `ctx.resolve(InboxChannelResolverToken)` to pick the right inbox channel
+* at runtime:
+* - In managed mode (PairingConfig present): routes to the control-plane inbox.
+* - Otherwise: routes to the local inbox.
+*
+* Authors use this node directly; no extra wiring needed per deployment mode.
+*/
+const inboxApproval = (0, __codemation_core.defineHumanApprovalNode)({
+	key: "inbox.approval",
+	title: "Inbox Approval",
+	description: "Suspend and wait for a human reviewer to approve or reject.",
+	icon: "lucide:inbox",
+	channel: "inbox",
+	configSchema: object({
+		title: custom((v) => typeof v === "string" || typeof v === "function"),
+		body: custom((v) => typeof v === "string" || typeof v === "function"),
+		priority: _enum([
+			"low",
+			"normal",
+			"high"
+		]).default("normal"),
+		timeout: string().default("24h"),
+		onTimeout: _enum(["halt", "auto-accept"]).default("halt")
+	}),
+	decisionSchema: object({
+		approved: boolean(),
+		note: string().optional()
+	}),
+	defaultTimeout: "24h",
+	defaultOnTimeout: "halt",
+	async deliver({ task, config: config$1, item }, ctx) {
+		const resolver = ctx.resolve(__codemation_core.InboxChannelResolverToken);
+		if (!resolver) throw new Error("inboxApproval: no InboxChannelResolver registered. Ensure the host DI container is wired.");
+		const { channel, workspaceId } = resolver.resolve();
+		const subject = {
+			title: resolveSubjectField(config$1.title, item),
+			summary: resolveSubjectField(config$1.body, item),
+			attributes: {
+				workflowId: ctx.workflowId,
+				item: item.json
+			}
+		};
+		const delivery = await channel.deliver({
+			task,
+			subject,
+			priority: config$1.priority,
+			item,
+			workspaceId
+		});
+		ctx.telemetry.addSpanEvent({
+			name: "hitl.task.delivered",
+			attributes: {
+				taskId: task.taskId,
+				channel: channel.kind
+			}
+		});
+		return delivery;
+	},
+	async onDecision({ decision, actor, delivery }, ctx) {
+		const resolver = ctx.resolve(__codemation_core.InboxChannelResolverToken);
+		if (!resolver) return;
+		const { channel } = resolver.resolve();
+		await channel.updateOnDecision?.({
+			delivery,
+			decision,
+			actor
+		});
+	},
+	async onTimeout({ delivery, policy }, ctx) {
+		const resolver = ctx.resolve(__codemation_core.InboxChannelResolverToken);
+		if (!resolver) return;
+		const { channel } = resolver.resolve();
+		await channel.updateOnTimeout?.({
+			delivery,
+			policy
+		});
+	}
+});
+
+//#endregion
+//#region src/nodes/codemationDocumentScannerNode.ts
+const ANALYZER_TYPES = [
+	"document",
+	"invoice",
+	"image",
+	"auto"
+];
+const codemationDocumentScannerNode = (0, __codemation_core.defineNode)({
+	key: "codemation.document-scanner",
+	title: "Codemation Document Scanner",
+	description: "Analyzes a binary attachment (document or image) via the managed Codemation document-scanning service and returns markdown text plus structured fields. No Azure credential required — auth uses the workspace pairing secret. Enable includeConfidence to get per-field confidence scores (0–1).",
+	icon: "lucide:scan-text",
+	input: {
+		binaryField: "data",
+		analyzerType: "auto",
+		contentType: void 0,
+		includeConfidence: false,
+		maxBytes: void 0
+	},
+	configSchema: object({
+		binaryField: string().optional(),
+		analyzerType: _enum(ANALYZER_TYPES).optional(),
+		contentType: string().optional(),
+		includeConfidence: boolean().optional(),
+		maxBytes: number().int().positive().optional()
+	}),
+	inspectorSummary({ config: config$1 }) {
+		const cfg = config$1;
+		const rows = [{
+			label: "Analyzer type",
+			value: cfg.analyzerType ?? "auto"
+		}];
+		const binaryField = cfg.binaryField ?? "data";
+		if (binaryField !== "data") rows.push({
+			label: "Binary field",
+			value: binaryField
+		});
+		if (cfg.includeConfidence) rows.push({
+			label: "Confidence",
+			value: "enabled"
+		});
+		if (cfg.contentType) rows.push({
+			label: "Content type",
+			value: cfg.contentType
+		});
+		return rows;
+	},
+	async execute({ item, ctx }, { config: rawConfig }) {
+		const config$1 = rawConfig;
+		const gatewayUrl = process.env["DOC_SCANNER_GATEWAY_URL"];
+		if (!gatewayUrl) throw new Error("Codemation Document Scanner not available in this environment (DOC_SCANNER_GATEWAY_URL is not set).");
+		const workspaceId = process.env["WORKSPACE_ID"];
+		const pairingSecret = process.env["WORKSPACE_PAIRING_SECRET"];
+		if (!workspaceId || !pairingSecret) throw new Error("Codemation Document Scanner not available (workspace pairing is not configured).");
+		const binaryField = config$1.binaryField ?? "data";
+		const attachment = item.binary?.[binaryField];
+		if (!attachment) throw new Error(`Codemation Document Scanner: no binary attachment at key "${binaryField}".`);
+		const body = await ctx.binary.getBytes(attachment, config$1.maxBytes);
+		const contentType = config$1.contentType ?? attachment.mimeType ?? "application/octet-stream";
+		const analyzerType = config$1.analyzerType ?? "auto";
+		const confidenceSuffix = config$1.includeConfidence ?? false ? "&confidence=true" : "";
+		const url = `${gatewayUrl}/analyze?type=${encodeURIComponent(analyzerType)}${confidenceSuffix}`;
+		const response = await managedHmacFetchFactory(workspaceId, pairingSecret, { signBody: false })(url, {
+			method: "POST",
+			body: body.buffer,
+			headers: {
+				"Content-Type": contentType,
+				"Content-Length": String(body.byteLength),
+				"X-Codemation-Caller": "workflow-node"
+			}
+		});
+		if (!response.ok) {
+			const text = await response.text().catch(() => "(unreadable)");
+			throw new Error(`Codemation Document Scanner: service responded ${response.status} ${response.statusText} — ${text}`);
+		}
+		return await response.json();
+	}
+});
+
 //#endregion
 exports.AIAgent = AIAgent;
 exports.AIAgentConnectionWorkflowExpander = AIAgentConnectionWorkflowExpander;
@@ -8986,6 +9370,7 @@ exports.WorkflowChain = WorkflowChain;
 exports.apiKeyCredentialType = apiKeyCredentialType;
 exports.basicAuthCredentialType = basicAuthCredentialType;
 exports.bearerTokenCredentialType = bearerTokenCredentialType;
+exports.codemationDocumentScannerNode = codemationDocumentScannerNode;
 exports.collectionDeleteNode = collectionDeleteNode;
 exports.collectionFindOneNode = collectionFindOneNode;
 exports.collectionGetNode = collectionGetNode;
@@ -8994,6 +9379,7 @@ exports.collectionListNode = collectionListNode;
 exports.collectionUpdateNode = collectionUpdateNode;
 exports.createWorkflowBuilder = createWorkflowBuilder;
 exports.defineRestNode = defineRestNode;
+exports.inboxApproval = inboxApproval;
 exports.oauth2ClientCredentialsType = oauth2ClientCredentialsType;
 exports.openAiChatModelPresets = openAiChatModelPresets;
 exports.registerCoreNodes = registerCoreNodes;