@codemation/core-nodes 0.1.1 → 0.2.0

package/dist/index.cjs

@@ -60,6 +60,42 @@ let OpenAIChatModelFactory = class OpenAIChatModelFactory$1 {
 };
 OpenAIChatModelFactory = __decorate([(0, __codemation_core.chatModel)({ packageName: "@codemation/core-nodes" })], OpenAIChatModelFactory);
 
+//#endregion
+//#region src/chatModels/OpenAIStructuredOutputMethodFactory.ts
+var _OpenAIStructuredOutputMethodFactory;
+let OpenAIStructuredOutputMethodFactory = class OpenAIStructuredOutputMethodFactory$1 {
+	static {
+		_OpenAIStructuredOutputMethodFactory = this;
+	}
+	static isoDatePattern = /^\d{4}-\d{2}-\d{2}$/;
+	create(chatModelConfig) {
+		if (chatModelConfig.type !== OpenAIChatModelFactory) return;
+		const model = this.readModelName(chatModelConfig);
+		if (!model) return {
+			method: "functionCalling",
+			strict: true
+		};
+		return {
+			method: this.supportsJsonSchema(model) ? "jsonSchema" : "functionCalling",
+			strict: true
+		};
+	}
+	readModelName(chatModelConfig) {
+		const candidate = chatModelConfig;
+		return typeof candidate.model === "string" ? candidate.model : void 0;
+	}
+	supportsJsonSchema(model) {
+		if (model === "gpt-4o" || model === "gpt-4o-mini") return true;
+		return this.supportsSnapshotAtOrAfter(model, "gpt-4o-", "2024-08-06") || this.supportsSnapshotAtOrAfter(model, "gpt-4o-mini-", "2024-07-18");
+	}
+	supportsSnapshotAtOrAfter(model, prefix, minimumSnapshotDate) {
+		if (!model.startsWith(prefix)) return false;
+		const snapshotDate = model.slice(prefix.length);
+		return _OpenAIStructuredOutputMethodFactory.isoDatePattern.test(snapshotDate) && snapshotDate >= minimumSnapshotDate;
+	}
+};
+OpenAIStructuredOutputMethodFactory = _OpenAIStructuredOutputMethodFactory = __decorate([(0, __codemation_core.injectable)()], OpenAIStructuredOutputMethodFactory);
+
 //#endregion
 //#region src/chatModels/openAiChatModelConfig.ts
 var OpenAIChatModelConfig = class {
@@ -171,14 +207,6 @@ var AgentOutputFactory = class {
 	}
 };
 
-//#endregion
-//#region src/nodes/AgentToolCallPortMapFactory.ts
-var AgentToolCallPortMap = class {
-	static fromInput(input) {
-		return { in: [{ json: input }] };
-	}
-};
-
 //#endregion
 //#region ../../node_modules/.pnpm/zod@4.3.6/node_modules/zod/v4/core/core.js
 /** A special constant with type `never` */
@@ -2070,6 +2098,168 @@ function toJSONSchema(input, params) {
 	return finalize(ctx, input);
 }
 
+//#endregion
+//#region src/nodes/ConnectionCredentialExecutionContextFactory.ts
+/**
+* Builds a {@link NodeExecutionContext} whose identity for credential binding and `getCredential`
+* is a **connection-owned** workflow node id (`ConnectionNodeIdFactory` in `@codemation/core`),
+* not the executing parent node. Use for LLM slots, tool slots, or any connection-scoped owner.
+*/
+var ConnectionCredentialExecutionContextFactory = class {
+	credentialResolverFactory;
+	constructor(credentialSessions) {
+		this.credentialResolverFactory = new __codemation_core_bootstrap.CredentialResolverFactory(credentialSessions);
+	}
+	forConnectionNode(ctx, args) {
+		const stubConfig = { getCredentialRequirements: args.getCredentialRequirements };
+		const getCredential = this.credentialResolverFactory.create(ctx.workflowId, args.connectionNodeId, stubConfig);
+		return {
+			...ctx,
+			nodeId: args.connectionNodeId,
+			getCredential
+		};
+	}
+};
+
+//#endregion
+//#region src/nodes/AIAgentExecutionHelpersFactory.ts
+let AIAgentExecutionHelpersFactory = class AIAgentExecutionHelpersFactory$1 {
+	createConnectionCredentialExecutionContextFactory(credentialSessions) {
+		return new ConnectionCredentialExecutionContextFactory(credentialSessions);
+	}
+	createDynamicStructuredTool(entry, toolCredentialContext, item, itemIndex, items) {
+		if (entry.runtime.inputSchema == null) throw new Error(`Cannot create LangChain tool "${entry.config.name}": missing inputSchema (broken tool runtime resolution).`);
+		const schemaForOpenAi = this.createJsonSchemaRecord(entry.runtime.inputSchema, {
+			schemaName: entry.config.name,
+			requireObjectRoot: true
+		});
+		return new __langchain_core_tools.DynamicStructuredTool({
+			name: entry.config.name,
+			description: entry.config.description ?? entry.runtime.defaultDescription,
+			schema: schemaForOpenAi,
+			func: async (input) => {
+				const result = await entry.runtime.execute({
+					config: entry.config,
+					input,
+					ctx: toolCredentialContext,
+					item,
+					itemIndex,
+					items
+				});
+				return JSON.stringify(result);
+			}
+		});
+	}
+	/**
+	* Produces a plain JSON Schema object for OpenAI tool parameters and LangChain tool invocation:
+	* - **Zod** → `toJSONSchema(..., { target: "draft-07" })` so shapes match what `@cfworker/json-schema`
+	*   expects (`required` must be an array; draft 2020-12 output can break validation).
+	* - Otherwise LangChain `toJsonSchema` (Standard Schema + JSON passthrough); if the result is still Zod
+	*   (duplicate `zod` copies), fall back to Zod `toJSONSchema` with draft-07.
+	* - Strip root `$schema` for OpenAI; normalize invalid `required` keywords for cfworker; ensure `properties`.
+	*/
+	createJsonSchemaRecord(inputSchema, options) {
+		const draft07Params = { target: "draft-07" };
+		let converted;
+		if ((0, __langchain_core_utils_types.isInteropZodSchema)(inputSchema)) converted = toJSONSchema(inputSchema, draft07Params);
+		else {
+			converted = (0, __langchain_core_utils_json_schema.toJsonSchema)(inputSchema);
+			if ((0, __langchain_core_utils_types.isInteropZodSchema)(converted)) converted = toJSONSchema(inputSchema, draft07Params);
+		}
+		const { $schema: _draftSchemaOmitted,...rest } = converted;
+		if (options.requireObjectRoot && rest.type !== "object") throw new Error(`Cannot create LangChain tool "${options.schemaName}": tool input schema must be a JSON Schema object type (got type=${String(rest.type)}).`);
+		if (options.requireObjectRoot && rest.properties !== void 0 && (typeof rest.properties !== "object" || Array.isArray(rest.properties))) throw new Error(`Cannot create LangChain tool "${options.schemaName}": tool input schema "properties" must be an object (got ${JSON.stringify(rest.properties)}).`);
+		if (options.requireObjectRoot && rest.properties === void 0) rest.properties = {};
+		this.sanitizeJsonSchemaRequiredKeywordsForCfworker(rest);
+		return rest;
+	}
+	/**
+	* `@cfworker/json-schema` iterates `schema.required` with `for...of`; it must be a string array or absent.
+	*/
+	sanitizeJsonSchemaRequiredKeywordsForCfworker(node$16) {
+		if (!node$16 || typeof node$16 !== "object" || Array.isArray(node$16)) return;
+		const o = node$16;
+		const req = o.required;
+		if (req !== void 0 && !Array.isArray(req)) delete o.required;
+		else if (Array.isArray(req)) {
+			const strings = req.filter((x) => typeof x === "string");
+			if (strings.length === 0) delete o.required;
+			else if (strings.length !== req.length) o.required = strings;
+		}
+		const props = o.properties;
+		if (props && typeof props === "object" && !Array.isArray(props)) for (const v of Object.values(props)) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(v);
+		for (const key of [
+			"allOf",
+			"anyOf",
+			"oneOf"
+		]) {
+			const branch = o[key];
+			if (Array.isArray(branch)) for (const sub of branch) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(sub);
+		}
+		if (o.if) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.if);
+		if (o.then) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.then);
+		if (o.else) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.else);
+		if (o.not) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.not);
+		if (o.items) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.items);
+		if (Array.isArray(o.prefixItems)) for (const sub of o.prefixItems) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(sub);
+	}
+};
+AIAgentExecutionHelpersFactory = __decorate([(0, __codemation_core.injectable)()], AIAgentExecutionHelpersFactory);
+
+//#endregion
+//#region \0@oxc-project+runtime@0.95.0/helpers/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.95.0/helpers/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+
+//#endregion
+//#region src/nodes/AgentStructuredOutputRepairPromptFactory.ts
+var _ref$3, _AgentStructuredOutputRepairPromptFactory;
+let AgentStructuredOutputRepairPromptFactory = class AgentStructuredOutputRepairPromptFactory$1 {
+	static {
+		_AgentStructuredOutputRepairPromptFactory = this;
+	}
+	static maxSchemaLength = 8e3;
+	static maxInvalidContentLength = 4e3;
+	static maxValidationErrorLength = 4e3;
+	constructor(executionHelpers) {
+		this.executionHelpers = executionHelpers;
+	}
+	create(args) {
+		return [{
+			role: "system",
+			content: "Return only JSON that matches the required schema exactly. Do not include markdown fences, commentary, or prose."
+		}, {
+			role: "user",
+			content: JSON.stringify({
+				requiredSchema: this.truncate(JSON.stringify(this.executionHelpers.createJsonSchemaRecord(args.schema, {
+					schemaName: "agent_output",
+					requireObjectRoot: false
+				})), _AgentStructuredOutputRepairPromptFactory.maxSchemaLength),
+				invalidModelOutput: this.truncate(args.invalidContent, _AgentStructuredOutputRepairPromptFactory.maxInvalidContentLength),
+				validationError: this.truncate(args.validationError, _AgentStructuredOutputRepairPromptFactory.maxValidationErrorLength)
+			})
+		}];
+	}
+	truncate(value, maxLength) {
+		if (value.length <= maxLength) return value;
+		return `${value.slice(0, maxLength)}...(truncated)`;
+	}
+};
+AgentStructuredOutputRepairPromptFactory = _AgentStructuredOutputRepairPromptFactory = __decorate([
+	(0, __codemation_core.injectable)(),
+	__decorateParam(0, (0, __codemation_core.inject)(AIAgentExecutionHelpersFactory)),
+	__decorateMetadata("design:paramtypes", [typeof (_ref$3 = typeof AIAgentExecutionHelpersFactory !== "undefined" && AIAgentExecutionHelpersFactory) === "function" ? _ref$3 : Object])
+], AgentStructuredOutputRepairPromptFactory);
+
 //#endregion
 //#region ../../node_modules/.pnpm/zod@4.3.6/node_modules/zod/v4/classic/errors.js
 const initializer = (inst, issues) => {
@@ -2401,132 +2591,140 @@ const describe = describe$1;
 const meta = meta$1;
 
 //#endregion
-//#region src/nodes/ConnectionCredentialExecutionContextFactory.ts
-/**
-* Builds a {@link NodeExecutionContext} whose identity for credential binding and `getCredential`
-* is a **connection-owned** workflow node id (`ConnectionNodeIdFactory` in `@codemation/core`),
-* not the executing parent node. Use for LLM slots, tool slots, or any connection-scoped owner.
-*/
-var ConnectionCredentialExecutionContextFactory = class {
-	credentialResolverFactory;
-	constructor(credentialSessions) {
-		this.credentialResolverFactory = new __codemation_core_bootstrap.CredentialResolverFactory(credentialSessions);
+//#region src/nodes/AgentStructuredOutputRunner.ts
+var _ref$2, _ref2$2, _AgentStructuredOutputRunner;
+let AgentStructuredOutputRunner = class AgentStructuredOutputRunner$1 {
+	static {
+		_AgentStructuredOutputRunner = this;
+	}
+	static repairAttemptCount = 2;
+	constructor(repairPromptFactory, openAiStructuredOutputMethodFactory) {
+		this.repairPromptFactory = repairPromptFactory;
+		this.openAiStructuredOutputMethodFactory = openAiStructuredOutputMethodFactory;
+	}
+	async resolve(args) {
+		let lastFailure;
+		if (args.rawFinalResponse) {
+			const directResult = this.tryParseAndValidate(AgentMessageFactory.extractContent(args.rawFinalResponse), args.schema);
+			if (directResult.ok) return directResult.value;
+			lastFailure = directResult;
+		} else if (!this.supportsNativeStructuredOutput(args.model)) {
+			const rawResponse = await args.invokeTextModel(args.conversation);
+			const directResult = this.tryParseAndValidate(AgentMessageFactory.extractContent(rawResponse), args.schema);
+			if (directResult.ok) return directResult.value;
+			lastFailure = directResult;
+		}
+		try {
+			const nativeStructuredModel = this.createStructuredOutputModel(args.model, args.chatModelConfig, args.schema);
+			if (nativeStructuredModel) {
+				const nativeResult = this.tryValidateStructuredValue(await args.invokeStructuredModel(nativeStructuredModel, args.conversation), args.schema);
+				if (nativeResult.ok) return nativeResult.value;
+				lastFailure = nativeResult;
+			}
+		} catch (error) {
+			lastFailure = {
+				ok: false,
+				invalidContent: "",
+				validationError: `Native structured output failed: ${this.summarizeError(error)}`
+			};
+		}
+		return await this.retryWithRepairPrompt({
+			...args,
+			lastFailure: lastFailure ?? {
+				ok: false,
+				invalidContent: "",
+				validationError: "Structured output was required but no valid structured response was produced."
+			}
+		});
 	}
-	forConnectionNode(ctx, args) {
-		const stubConfig = { getCredentialRequirements: args.getCredentialRequirements };
-		const getCredential = this.credentialResolverFactory.create(ctx.workflowId, args.connectionNodeId, stubConfig);
-		return {
-			...ctx,
-			nodeId: args.connectionNodeId,
-			getCredential
-		};
+	async retryWithRepairPrompt(args) {
+		let failure = args.lastFailure;
+		for (let attempt = 1; attempt <= _AgentStructuredOutputRunner.repairAttemptCount; attempt++) {
+			const repairMessages = [...args.conversation, ...AgentMessageFactory.createPromptMessages(this.repairPromptFactory.create({
+				schema: args.schema,
+				invalidContent: failure.invalidContent,
+				validationError: failure.validationError
+			}))];
+			const repairResponse = await args.invokeTextModel(repairMessages);
+			const repairResult = this.tryParseAndValidate(AgentMessageFactory.extractContent(repairResponse), args.schema);
+			if (repairResult.ok) return repairResult.value;
+			failure = repairResult;
+		}
+		throw new Error(`Structured output required for AIAgent "${args.agentName}" (${args.nodeId}) but validation still failed after ${_AgentStructuredOutputRunner.repairAttemptCount} repair attempts: ${failure.validationError}`);
 	}
-};
-
-//#endregion
-//#region src/nodes/AIAgentExecutionHelpersFactory.ts
-let AIAgentExecutionHelpersFactory = class AIAgentExecutionHelpersFactory$1 {
-	createConnectionCredentialExecutionContextFactory(credentialSessions) {
-		return new ConnectionCredentialExecutionContextFactory(credentialSessions);
+	createStructuredOutputModel(model, chatModelConfig, schema) {
+		if (!this.supportsNativeStructuredOutput(model)) return;
+		const options = this.getStructuredOutputOptions(chatModelConfig);
+		return model.withStructuredOutput(schema, options);
 	}
-	createDynamicStructuredTool(entry, toolCredentialContext, item, itemIndex, items) {
-		if (entry.runtime.inputSchema == null) throw new Error(`Cannot create LangChain tool "${entry.config.name}": missing inputSchema (broken tool runtime resolution).`);
-		const schemaForOpenAi = this.normalizeToolInputSchemaForOpenAiDynamicStructuredTool(entry.config.name, entry.runtime.inputSchema);
-		return new __langchain_core_tools.DynamicStructuredTool({
-			name: entry.config.name,
-			description: entry.config.description ?? entry.runtime.defaultDescription,
-			schema: schemaForOpenAi,
-			func: async (input) => {
-				const result = await entry.runtime.execute({
-					config: entry.config,
-					input,
-					ctx: toolCredentialContext,
-					item,
-					itemIndex,
-					items
-				});
-				return JSON.stringify(result);
-			}
-		});
+	getStructuredOutputOptions(chatModelConfig) {
+		return this.openAiStructuredOutputMethodFactory.create(chatModelConfig) ?? { strict: true };
 	}
-	/**
-	* Produces a plain JSON Schema object for OpenAI tool parameters and LangChain tool invocation:
-	* - **Zod** → `toJSONSchema(..., { target: "draft-07" })` so shapes match what `@cfworker/json-schema`
-	*   expects (`required` must be an array; draft 2020-12 output can break validation).
-	* - Otherwise LangChain `toJsonSchema` (Standard Schema + JSON passthrough); if the result is still Zod
-	*   (duplicate `zod` copies), fall back to Zod `toJSONSchema` with draft-07.
-	* - Strip root `$schema` for OpenAI; normalize invalid `required` keywords for cfworker; ensure `properties`.
-	*/
-	normalizeToolInputSchemaForOpenAiDynamicStructuredTool(toolName, inputSchema) {
-		const draft07Params = { target: "draft-07" };
-		let converted;
-		if ((0, __langchain_core_utils_types.isInteropZodSchema)(inputSchema)) converted = toJSONSchema(inputSchema, draft07Params);
-		else {
-			converted = (0, __langchain_core_utils_json_schema.toJsonSchema)(inputSchema);
-			if ((0, __langchain_core_utils_types.isInteropZodSchema)(converted)) converted = toJSONSchema(inputSchema, draft07Params);
+	supportsNativeStructuredOutput(model) {
+		return typeof model.withStructuredOutput === "function";
+	}
+	tryParseAndValidate(content, schema) {
+		try {
+			return this.tryValidateStructuredValue(JSON.parse(content), schema, content);
+		} catch (error) {
+			return {
+				ok: false,
+				invalidContent: content,
+				validationError: `Response was not valid JSON: ${this.summarizeError(error)}`
+			};
 		}
-		const { $schema: _draftSchemaOmitted,...rest } = converted;
-		if (rest.type !== "object") throw new Error(`Cannot create LangChain tool "${toolName}": tool input schema must be a JSON Schema object type (got type=${String(rest.type)}).`);
-		if (rest.properties !== void 0 && (typeof rest.properties !== "object" || Array.isArray(rest.properties))) throw new Error(`Cannot create LangChain tool "${toolName}": tool input schema "properties" must be an object (got ${JSON.stringify(rest.properties)}).`);
-		if (rest.properties === void 0) rest.properties = {};
-		this.sanitizeJsonSchemaRequiredKeywordsForCfworker(rest);
-		return rest;
 	}
-	/**
-	* `@cfworker/json-schema` iterates `schema.required` with `for...of`; it must be a string array or absent.
-	*/
-	sanitizeJsonSchemaRequiredKeywordsForCfworker(node$16) {
-		if (!node$16 || typeof node$16 !== "object" || Array.isArray(node$16)) return;
-		const o = node$16;
-		const req = o.required;
-		if (req !== void 0 && !Array.isArray(req)) delete o.required;
-		else if (Array.isArray(req)) {
-			const strings = req.filter((x) => typeof x === "string");
-			if (strings.length === 0) delete o.required;
-			else if (strings.length !== req.length) o.required = strings;
+	tryValidateStructuredValue(value, schema, invalidContent) {
+		try {
+			return {
+				ok: true,
+				value: schema.parse(value)
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				invalidContent: invalidContent ?? this.toJson(value),
+				validationError: this.summarizeError(error)
+			};
 		}
-		const props = o.properties;
-		if (props && typeof props === "object" && !Array.isArray(props)) for (const v of Object.values(props)) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(v);
-		for (const key of [
-			"allOf",
-			"anyOf",
-			"oneOf"
-		]) {
-			const branch = o[key];
-			if (Array.isArray(branch)) for (const sub of branch) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(sub);
+	}
+	summarizeError(error) {
+		if (error instanceof ZodError) return error.issues.map((issue$1) => `${issue$1.path.join(".") || "<root>"}: ${issue$1.message}`).join("; ");
+		if (error instanceof Error) return error.message;
+		return String(error);
+	}
+	toJson(value) {
+		try {
+			return JSON.stringify(value);
+		} catch (error) {
+			return `<<unserializable: ${this.summarizeError(error)}>>`;
 		}
-		if (o.if) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.if);
-		if (o.then) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.then);
-		if (o.else) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.else);
-		if (o.not) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.not);
-		if (o.items) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(o.items);
-		if (Array.isArray(o.prefixItems)) for (const sub of o.prefixItems) this.sanitizeJsonSchemaRequiredKeywordsForCfworker(sub);
 	}
 };
-AIAgentExecutionHelpersFactory = __decorate([(0, __codemation_core.injectable)()], AIAgentExecutionHelpersFactory);
-
-//#endregion
-//#region \0@oxc-project+runtime@0.95.0/helpers/decorateMetadata.js
-function __decorateMetadata(k, v) {
-	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
+AgentStructuredOutputRunner = _AgentStructuredOutputRunner = __decorate([
+	(0, __codemation_core.injectable)(),
+	__decorateParam(0, (0, __codemation_core.inject)(AgentStructuredOutputRepairPromptFactory)),
+	__decorateParam(1, (0, __codemation_core.inject)(OpenAIStructuredOutputMethodFactory)),
+	__decorateMetadata("design:paramtypes", [typeof (_ref$2 = typeof AgentStructuredOutputRepairPromptFactory !== "undefined" && AgentStructuredOutputRepairPromptFactory) === "function" ? _ref$2 : Object, typeof (_ref2$2 = typeof OpenAIStructuredOutputMethodFactory !== "undefined" && OpenAIStructuredOutputMethodFactory) === "function" ? _ref2$2 : Object])
+], AgentStructuredOutputRunner);
 
 //#endregion
-//#region \0@oxc-project+runtime@0.95.0/helpers/decorateParam.js
-function __decorateParam(paramIndex, decorator) {
-	return function(target, key) {
-		decorator(target, key, paramIndex);
-	};
-}
+//#region src/nodes/AgentToolCallPortMapFactory.ts
+var AgentToolCallPortMap = class {
+	static fromInput(input) {
+		return { in: [{ json: input }] };
+	}
+};
 
 //#endregion
 //#region src/nodes/NodeBackedToolRuntime.ts
-var _ref$1, _ref2$1;
+var _ref$1, _ref2$1, _ref3$1;
 let NodeBackedToolRuntime = class NodeBackedToolRuntime$1 {
-	constructor(nodeResolver, itemValueResolver, outputNormalizer) {
+	constructor(nodeResolver, itemValueResolver, outputNormalizer, outputBehaviorResolver) {
 		this.nodeResolver = nodeResolver;
 		this.itemValueResolver = itemValueResolver;
 		this.outputNormalizer = outputNormalizer;
+		this.outputBehaviorResolver = outputBehaviorResolver;
 	}
 	async execute(config$1, args) {
 		const nodeInput = config$1.toNodeItem({
@@ -2558,7 +2756,7 @@ let NodeBackedToolRuntime = class NodeBackedToolRuntime$1 {
 		if (this.isRunnableNode(resolvedNode)) {
 			const runnable = resolvedNode;
 			const runnableConfig = ctx.config;
-			const carry = runnableConfig.lineageCarry ?? "emitOnly";
+			const behavior = this.outputBehaviorResolver.resolve(runnableConfig);
 			const parsed = (runnable.inputSchema ?? runnableConfig.inputSchema ?? unknown()).parse(nodeInput.json);
 			const items = [nodeInput];
 			const execArgs = {
@@ -2572,7 +2770,7 @@ let NodeBackedToolRuntime = class NodeBackedToolRuntime$1 {
 			return this.outputNormalizer.normalizeExecuteResult({
 				baseItem: nodeInput,
 				raw,
-				carry
+				behavior
 			});
 		}
 		throw new Error(`Node-backed tool expected a runnable node instance for "${ctx.config.name ?? ctx.nodeId}".`);
@@ -2589,10 +2787,12 @@ NodeBackedToolRuntime = __decorate([
 	__decorateParam(0, (0, __codemation_core.inject)(__codemation_core.CoreTokens.NodeResolver)),
 	__decorateParam(1, (0, __codemation_core.inject)(__codemation_core.ItemValueResolver)),
 	__decorateParam(2, (0, __codemation_core.inject)(__codemation_core.NodeOutputNormalizer)),
+	__decorateParam(3, (0, __codemation_core.inject)(__codemation_core.RunnableOutputBehaviorResolver)),
 	__decorateMetadata("design:paramtypes", [
 		Object,
 		typeof (_ref$1 = typeof __codemation_core.ItemValueResolver !== "undefined" && __codemation_core.ItemValueResolver) === "function" ? _ref$1 : Object,
-		typeof (_ref2$1 = typeof __codemation_core.NodeOutputNormalizer !== "undefined" && __codemation_core.NodeOutputNormalizer) === "function" ? _ref2$1 : Object
+		typeof (_ref2$1 = typeof __codemation_core.NodeOutputNormalizer !== "undefined" && __codemation_core.NodeOutputNormalizer) === "function" ? _ref2$1 : Object,
+		typeof (_ref3$1 = typeof __codemation_core.RunnableOutputBehaviorResolver !== "undefined" && __codemation_core.RunnableOutputBehaviorResolver) === "function" ? _ref3$1 : Object
 	])
 ], NodeBackedToolRuntime);
 
@@ -2606,7 +2806,7 @@ var AgentItemPortMap = class {
 
 //#endregion
 //#region src/nodes/AIAgentNode.ts
-var _ref, _ref2;
+var _ref, _ref2, _ref3;
 let AIAgentNode = class AIAgentNode$1 {
 	kind = "node";
 	outputPorts = ["main"];
@@ -2619,10 +2819,11 @@ let AIAgentNode = class AIAgentNode$1 {
 	connectionCredentialExecutionContextFactory;
 	/** One resolved model/tools bundle per activation context (same ctx across items in a batch). */
 	preparedByExecutionContext = /* @__PURE__ */ new WeakMap();
-	constructor(nodeResolver, credentialSessions, nodeBackedToolRuntime, executionHelpers) {
+	constructor(nodeResolver, credentialSessions, nodeBackedToolRuntime, executionHelpers, structuredOutputRunner) {
 		this.nodeResolver = nodeResolver;
 		this.nodeBackedToolRuntime = nodeBackedToolRuntime;
 		this.executionHelpers = executionHelpers;
+		this.structuredOutputRunner = structuredOutputRunner;
 		this.connectionCredentialExecutionContextFactory = this.executionHelpers.createConnectionCredentialExecutionContextFactory(credentialSessions);
 	}
 	async execute(args) {
@@ -2674,6 +2875,19 @@ let AIAgentNode = class AIAgentNode$1 {
 		const itemInputsByPort = AgentItemPortMap.fromItem(item);
 		const itemScopedTools = this.createItemScopedTools(prepared.resolvedTools, ctx, item, itemIndex, items);
 		const conversation = [...this.createPromptMessages(item, itemIndex, items, ctx)];
+		if (ctx.config.outputSchema && itemScopedTools.length === 0) {
+			const structuredOutput = await this.structuredOutputRunner.resolve({
+				model: prepared.model,
+				chatModelConfig: ctx.config.chatModel,
+				schema: ctx.config.outputSchema,
+				conversation,
+				agentName: this.getAgentDisplayName(ctx),
+				nodeId: ctx.nodeId,
+				invokeTextModel: async (messages) => await this.invokeModel(prepared.model, prepared.languageModelConnectionNodeId, messages, ctx, itemInputsByPort, prepared.guardrails.modelInvocationOptions),
+				invokeStructuredModel: async (structuredModel, messages) => await this.invokeStructuredModel(structuredModel, prepared.languageModelConnectionNodeId, messages, ctx, itemInputsByPort, prepared.guardrails.modelInvocationOptions)
+			});
+			return this.buildOutputItem(item, structuredOutput);
+		}
 		const modelWithTools = this.bindToolsToModel(prepared.model, itemScopedTools);
 		const finalResponse = await this.runTurnLoopUntilFinalAnswer({
 			prepared,
@@ -2682,7 +2896,8 @@ let AIAgentNode = class AIAgentNode$1 {
 			conversation,
 			modelWithTools
 		});
-		return this.buildOutputItem(item, finalResponse);
+		const outputJson = await this.resolveFinalOutputJson(prepared, itemInputsByPort, conversation, finalResponse, itemScopedTools.length > 0);
+		return this.buildOutputItem(item, outputJson);
 	}
 	/**
 	* Repeatedly invokes the model until it returns without tool calls, or guardrails end the loop.
@@ -2718,8 +2933,22 @@ let AIAgentNode = class AIAgentNode$1 {
 	appendAssistantAndToolMessages(conversation, assistantMessage, executedToolCalls) {
 		conversation.push(assistantMessage, ...executedToolCalls.map((toolCall) => AgentMessageFactory.createToolMessage(toolCall.toolCallId, toolCall.serialized)));
 	}
-	buildOutputItem(item, finalResponse) {
-		return AgentOutputFactory.replaceJson(item, AgentOutputFactory.fromAgentContent(AgentMessageFactory.extractContent(finalResponse)));
+	async resolveFinalOutputJson(prepared, itemInputsByPort, conversation, finalResponse, wasToolEnabledRun) {
+		if (!prepared.ctx.config.outputSchema) return AgentOutputFactory.fromAgentContent(AgentMessageFactory.extractContent(finalResponse));
+		return await this.structuredOutputRunner.resolve({
+			model: prepared.model,
+			chatModelConfig: prepared.ctx.config.chatModel,
+			schema: prepared.ctx.config.outputSchema,
+			conversation: wasToolEnabledRun ? [...conversation, finalResponse] : conversation,
+			rawFinalResponse: finalResponse,
+			agentName: this.getAgentDisplayName(prepared.ctx),
+			nodeId: prepared.ctx.nodeId,
+			invokeTextModel: async (messages) => await this.invokeModel(prepared.model, prepared.languageModelConnectionNodeId, messages, prepared.ctx, itemInputsByPort, prepared.guardrails.modelInvocationOptions),
+			invokeStructuredModel: async (structuredModel, messages) => await this.invokeStructuredModel(structuredModel, prepared.languageModelConnectionNodeId, messages, prepared.ctx, itemInputsByPort, prepared.guardrails.modelInvocationOptions)
+		});
+	}
+	buildOutputItem(item, outputJson) {
+		return AgentOutputFactory.replaceJson(item, outputJson);
 	}
 	bindToolsToModel(model, itemScopedTools) {
 		if (itemScopedTools.length === 0 || !model.bindTools) return model;
@@ -2785,6 +3014,40 @@ let AIAgentNode = class AIAgentNode$1 {
 			throw await this.failTrackedNodeInvocation(error, nodeId, ctx, inputsByPort, this.summarizeLlmMessages(messages));
 		}
 	}
+	async invokeStructuredModel(model, nodeId, messages, ctx, inputsByPort, options) {
+		await ctx.nodeState?.markQueued({
+			nodeId,
+			activationId: ctx.activationId,
+			inputsByPort
+		});
+		await ctx.nodeState?.markRunning({
+			nodeId,
+			activationId: ctx.activationId,
+			inputsByPort
+		});
+		try {
+			const response = await model.invoke(messages, options);
+			await ctx.nodeState?.markCompleted({
+				nodeId,
+				activationId: ctx.activationId,
+				inputsByPort,
+				outputs: AgentOutputFactory.fromUnknown(response)
+			});
+			await ctx.nodeState?.appendConnectionInvocation({
+				invocationId: __codemation_core.ConnectionInvocationIdFactory.create(),
+				connectionNodeId: nodeId,
+				parentAgentNodeId: ctx.nodeId,
+				parentAgentActivationId: ctx.activationId,
+				status: "completed",
+				managedInput: this.summarizeLlmMessages(messages),
+				managedOutput: this.resultToJsonValue(response),
+				finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return response;
+		} catch (error) {
+			throw await this.failTrackedNodeInvocation(error, nodeId, ctx, inputsByPort, this.summarizeLlmMessages(messages));
+		}
+	}
 	async markQueuedTools(plannedToolCalls, ctx) {
 		for (const plannedToolCall of plannedToolCalls) await ctx.nodeState?.markQueued({
 			nodeId: plannedToolCall.nodeId,
@@ -2914,6 +3177,18 @@ let AIAgentNode = class AIAgentNode$1 {
 				execute: async (args) => await this.nodeBackedToolRuntime.execute(config$1, args)
 			};
 		}
+		if (this.isCallableToolConfig(config$1)) {
+			const inputSchema = config$1.getInputSchema();
+			if (inputSchema == null) throw new Error(`AIAgent tool "${config$1.name}": callable tool is missing inputSchema (cannot build LangChain tool).`);
+			return {
+				defaultDescription: config$1.description ?? `Callable tool "${config$1.name}".`,
+				inputSchema,
+				execute: async (args) => await config$1.executeTool({
+					...args,
+					config: config$1
+				})
+			};
+		}
 		const tool = this.nodeResolver.resolve(config$1.type);
 		if (tool.inputSchema == null) throw new Error(`AIAgent tool "${config$1.name}": plugin tool "${String(config$1.type)}" is missing inputSchema.`);
 		return {
@@ -2930,6 +3205,12 @@ let AIAgentNode = class AIAgentNode$1 {
 	isNodeBackedToolConfig(config$1) {
 		return config$1 instanceof __codemation_core.NodeBackedToolConfig || typeof config$1 === "object" && config$1 !== null && config$1.toolKind === "nodeBacked";
 	}
+	/**
+	* Callable tools use {@link CallableToolConfig#toolKind} for cross-package / JSON round-trip safety.
+	*/
+	isCallableToolConfig(config$1) {
+		return config$1 instanceof __codemation_core.CallableToolConfig || typeof config$1 === "object" && config$1 !== null && config$1.toolKind === "callable";
+	}
 	resolveGuardrails(guardrails) {
 		const maxTurns = guardrails?.maxTurns ?? __codemation_core.AgentGuardrailDefaults.maxTurns;
 		if (!Number.isInteger(maxTurns) || maxTurns < 1) throw new Error(`AIAgent maxTurns must be a positive integer. Received: ${String(maxTurns)}`);
@@ -2939,6 +3220,9 @@ let AIAgentNode = class AIAgentNode$1 {
 			modelInvocationOptions: guardrails?.modelInvocationOptions
 		};
 	}
+	getAgentDisplayName(ctx) {
+		return ctx.config.name ?? ctx.nodeId;
+	}
 };
 AIAgentNode = __decorate([
 	(0, __codemation_core.node)({ packageName: "@codemation/core-nodes" }),
@@ -2946,11 +3230,13 @@ AIAgentNode = __decorate([
 	__decorateParam(1, (0, __codemation_core.inject)(__codemation_core.CoreTokens.CredentialSessionService)),
 	__decorateParam(2, (0, __codemation_core.inject)(NodeBackedToolRuntime)),
 	__decorateParam(3, (0, __codemation_core.inject)(AIAgentExecutionHelpersFactory)),
+	__decorateParam(4, (0, __codemation_core.inject)(AgentStructuredOutputRunner)),
 	__decorateMetadata("design:paramtypes", [
 		Object,
 		Object,
 		typeof (_ref = typeof NodeBackedToolRuntime !== "undefined" && NodeBackedToolRuntime) === "function" ? _ref : Object,
-		typeof (_ref2 = typeof AIAgentExecutionHelpersFactory !== "undefined" && AIAgentExecutionHelpersFactory) === "function" ? _ref2 : Object
+		typeof (_ref2 = typeof AIAgentExecutionHelpersFactory !== "undefined" && AIAgentExecutionHelpersFactory) === "function" ? _ref2 : Object,
+		typeof (_ref3 = typeof AgentStructuredOutputRunner !== "undefined" && AgentStructuredOutputRunner) === "function" ? _ref3 : Object
 	])
 ], AIAgentNode);
 
@@ -2973,6 +3259,7 @@ var AIAgent = class {
 	retryPolicy;
 	guardrails;
 	inputSchema;
+	outputSchema;
 	constructor(options) {
 		this.name = options.name;
 		this.messages = options.messages;
@@ -2982,6 +3269,7 @@ var AIAgent = class {
 		this.retryPolicy = options.retryPolicy ?? __codemation_core.RetryPolicy.defaultForAiAgent;
 		this.guardrails = options.guardrails;
 		this.inputSchema = options.inputSchema;
+		this.outputSchema = options.outputSchema;
 	}
 };
 
@@ -3298,7 +3586,6 @@ var Switch = class {
 	type = SwitchNode;
 	execution = { hint: "local" };
 	icon = "lucide:git-branch-plus";
-	lineageCarry = "carryThrough";
 	declaredOutputPorts;
 	constructor(name, cfg, id) {
 		this.name = name;
@@ -3401,10 +3688,15 @@ var MapData = class {
 	execution = { hint: "local" };
 	/** Zero mapped items should still allow downstream nodes to run. */
 	continueWhenEmptyOutput = true;
-	constructor(name, map, id) {
+	keepBinaries;
+	constructor(name, map, options = {}) {
 		this.name = name;
 		this.map = map;
-		this.id = id;
+		this.options = options;
+		this.keepBinaries = options.keepBinaries ?? true;
+	}
+	get id() {
+		return this.options.id;
 	}
 };
 
@@ -3713,15 +4005,13 @@ var WorkflowAgentNodeFactory = class {
 	static create(nameOrOptions, optionsOrUndefined) {
 		const options = typeof nameOrOptions === "string" ? optionsOrUndefined : nameOrOptions;
 		const name = typeof nameOrOptions === "string" ? nameOrOptions : "AI agent";
-		const prompt = options.prompt;
+		const outputSchema = options.outputSchema;
 		return new AIAgent({
 			name,
-			messages: [{
-				role: "user",
-				content: typeof prompt === "function" ? ({ item }) => prompt(item.json) : prompt
-			}],
+			messages: options.messages,
 			chatModel: WorkflowChatModelFactory.create(options.model),
 			tools: options.tools,
+			outputSchema,
 			id: options.id,
 			retryPolicy: options.retryPolicy,
 			guardrails: options.guardrails
@@ -3765,10 +4055,10 @@ var WorkflowBranchBuilder = class WorkflowBranchBuilder {
 	then(config$1) {
 		return new WorkflowBranchBuilder([...this.steps, config$1]);
 	}
-	map(nameOrMapper, mapperOrUndefined, id) {
+	map(nameOrMapper, mapperOrUndefined, options) {
 		const name = typeof nameOrMapper === "string" ? nameOrMapper : "Map data";
 		const mapper = typeof nameOrMapper === "string" ? mapperOrUndefined : nameOrMapper;
-		return this.then(new MapData(name, (item) => mapper(item.json), id));
+		return this.then(new MapData(name, (item) => mapper(item.json), options));
 	}
 	wait(nameOrDuration, durationOrUndefined, id) {
 		const name = typeof nameOrDuration === "string" && durationOrUndefined !== void 0 ? nameOrDuration : "Wait";
@@ -3811,10 +4101,10 @@ var WorkflowChain = class WorkflowChain {
 	then(config$1) {
 		return new WorkflowChain(this.chain.then(config$1));
 	}
-	map(nameOrMapper, mapperOrUndefined, id) {
+	map(nameOrMapper, mapperOrUndefined, options) {
 		const name = typeof nameOrMapper === "string" ? nameOrMapper : "Map data";
 		const mapper = typeof nameOrMapper === "string" ? mapperOrUndefined : nameOrMapper;
-		return this.then(new MapData(name, (item) => mapper(item.json), id));
+		return this.then(new MapData(name, (item) => mapper(item.json), options));
 	}
 	wait(nameOrDuration, durationOrUndefined, id) {
 		const name = typeof nameOrDuration === "string" && durationOrUndefined !== void 0 ? nameOrDuration : "Wait";
@@ -4018,6 +4308,18 @@ Object.defineProperty(exports, 'AIAgentNode', {
 exports.AgentItemPortMap = AgentItemPortMap;
 exports.AgentMessageFactory = AgentMessageFactory;
 exports.AgentOutputFactory = AgentOutputFactory;
+Object.defineProperty(exports, 'AgentStructuredOutputRepairPromptFactory', {
+  enumerable: true,
+  get: function () {
+    return AgentStructuredOutputRepairPromptFactory;
+  }
+});
+Object.defineProperty(exports, 'AgentStructuredOutputRunner', {
+  enumerable: true,
+  get: function () {
+    return AgentStructuredOutputRunner;
+  }
+});
 exports.AgentToolCallPortMap = AgentToolCallPortMap;
 exports.Aggregate = Aggregate;
 Object.defineProperty(exports, 'AggregateNode', {
@@ -4099,6 +4401,12 @@ Object.defineProperty(exports, 'OpenAIChatModelFactory', {
     return OpenAIChatModelFactory;
   }
 });
+Object.defineProperty(exports, 'OpenAIStructuredOutputMethodFactory', {
+  enumerable: true,
+  get: function () {
+    return OpenAIStructuredOutputMethodFactory;
+  }
+});
 exports.OpenAiChatModelPresets = OpenAiChatModelPresets;
 exports.Split = Split;
 Object.defineProperty(exports, 'SplitNode', {