llmz 0.9.0 → 1.0.2

package/dist/{tool-Dy6AJpJH.cjs → tool-_wK9hQOb.cjs}

@@ -1,9 +1,59 @@
-const require_compiler = require("./compiler-C-OI9sim.cjs");
-const require_uniq = require("./uniq-G872RWmE.cjs");
-const require_utils = require("./utils-3ESwP3yg.cjs");
-const require_isEmpty = require("./isEmpty-LY533Wmh.cjs");
-const require_typings = require("./typings-3lsqCbkn.cjs");
+const require_utils = require("./utils-CTlsXvdj.cjs");
+const require_errors = require("./errors-C6ppQUZX.cjs");
+const require_uniq = require("./uniq-DiXgysNV.cjs");
+const require_schema = require("./schema-CXlnbb3n.cjs");
+const require_truncate = require("./truncate-uomAMGPs.cjs");
+const require_typings = require("./typings-BA_XxAcY.cjs");
 let _bpinternal_zui = require("@bpinternal/zui");
+//#region ../../node_modules/.pnpm/lodash-es@4.17.21/node_modules/lodash-es/isEmpty.js
+/** `Object#toString` result references. */
+var mapTag = "[object Map]";
+var setTag = "[object Set]";
+/** Used to check objects for own properties. */
+var hasOwnProperty = Object.prototype.hasOwnProperty;
+/**
+* Checks if `value` is an empty object, collection, map, or set.
+*
+* Objects are considered empty if they have no own enumerable string keyed
+* properties.
+*
+* Array-like values such as `arguments` objects, arrays, buffers, strings, or
+* jQuery-like collections are considered empty if they have a `length` of `0`.
+* Similarly, maps and sets are considered empty if they have a `size` of `0`.
+*
+* @static
+* @memberOf _
+* @since 0.1.0
+* @category Lang
+* @param {*} value The value to check.
+* @returns {boolean} Returns `true` if `value` is empty, else `false`.
+* @example
+*
+* _.isEmpty(null);
+* // => true
+*
+* _.isEmpty(true);
+* // => true
+*
+* _.isEmpty(1);
+* // => true
+*
+* _.isEmpty([1, 2, 3]);
+* // => false
+*
+* _.isEmpty({ 'a': 1 });
+* // => false
+*/
+function isEmpty(value) {
+	if (value == null) return true;
+	if (require_utils.isArrayLike(value) && (require_utils.isArray(value) || typeof value == "string" || typeof value.splice == "function" || require_utils.isBuffer(value) || require_utils.isTypedArray(value) || require_utils.isArguments(value))) return !value.length;
+	var tag = require_utils._getTag_default(value);
+	if (tag == mapTag || tag == setTag) return !value.size;
+	if (require_utils.isPrototype(value)) return !require_utils.baseKeys(value).length;
+	for (var key in value) if (hasOwnProperty.call(value, key)) return false;
+	return true;
+}
+//#endregion
 //#region src/convert.ts
 function convertObjectToZuiLiterals(obj, nested = false) {
 	if (typeof obj === "string") return _bpinternal_zui.z.literal(obj).catch(() => obj);
@@ -27,7 +77,7 @@ function convertObjectToZuiLiterals(obj, nested = false) {
 }
 //#endregion
 //#region src/tool.ts
-var tool_exports = /* @__PURE__ */ require_compiler.__exportAll({ Tool: () => Tool });
+var tool_exports = /* @__PURE__ */ require_utils.__exportAll({ Tool: () => Tool });
 /**
 * Tool represents a callable function that agents can use to interact with external systems.
 *
@@ -37,7 +87,7 @@ var tool_exports = /* @__PURE__ */ require_compiler.__exportAll({ Tool: () => To
 *
 * ## Key Features
 * - **Type Safety**: Full TypeScript inference with Zui/Zod schema validation
-* - **Input/Output Validation**: Automatic validation of inputs and outputs against schemas
+* - **Input Validation**: Parse inputs through their original schema; output schemas are documentation only
 * - **Retry Logic**: Built-in retry mechanisms with custom retry functions
 * - **Static Values**: Pre-configure parameters that won't change between calls
 * - **Tool Cloning**: Create variations of existing tools with modified behavior
@@ -164,7 +214,7 @@ var tool_exports = /* @__PURE__ */ require_compiler.__exportAll({ Tool: () => To
 *
 * Tools automatically handle:
 * - **Input validation**: Invalid inputs throw descriptive errors
-* - **Output validation**: Outputs are validated but invalid outputs are still returned
+* - **Output hints**: Schemas describe likely outputs; results are never parsed or rejected
 * - **Handler errors**: Exceptions in handlers are caught and can trigger retries
 * - **Type coercion**: Basic type coercion where possible
 *
@@ -175,7 +225,9 @@ var Tool = class Tool {
 	aliases = [];
 	description;
 	metadata;
+	/** Model-facing input description; zInput retains the original validator. */
 	input;
+	/** Expected raw output shape, used for documentation only. */
 	output;
 	retry;
 	MAX_RETRIES = 1e3;
@@ -226,8 +278,8 @@ var Tool = class Tool {
 			return this;
 		}
 		const input = this.input ? require_utils.fromJSONSchemaCompat(this.input) : _bpinternal_zui.z.any();
-		if (_bpinternal_zui.z.is.zuiObject(input) && typeof values !== "object") throw new Error(`Invalid static input values for tool ${this.name}. Expected an object, but got type "${typeof values}"`);
-		if (_bpinternal_zui.z.is.zuiArray(input) && !Array.isArray(values)) throw new Error(`Invalid static input values for tool ${this.name}. Expected an array, but got type "${typeof values}"`);
+		if (_bpinternal_zui.z.is.zuiObject(input) && typeof values !== "object") throw new require_errors.InvalidToolError(`Invalid static input values for tool ${this.name}. Expected an object, but got type "${typeof values}"`);
+		if (_bpinternal_zui.z.is.zuiArray(input) && !Array.isArray(values)) throw new require_errors.InvalidToolError(`Invalid static input values for tool ${this.name}. Expected an array, but got type "${typeof values}"`);
 		this._staticInputValues = values;
 		return this;
 	}
@@ -241,28 +293,19 @@ var Tool = class Tool {
 	* @internal
 	*/
 	get zInput() {
-		let input;
-		if (this.input) try {
-			input = _bpinternal_zui.transforms.fromJSONSchema(this.input);
-		} catch {
-			input = _bpinternal_zui.transforms.fromJSONSchemaLegacy(this.input);
-		}
-		else input = _bpinternal_zui.z.any();
-		if (!require_isEmpty.isEmpty(this._staticInputValues)) {
-			if (_bpinternal_zui.z.is.zuiObject(input)) {
-				const inputExtensions = convertObjectToZuiLiterals(this._staticInputValues);
-				input = input.extend(inputExtensions);
-			} else if (_bpinternal_zui.z.is.zuiArray(input)) {
-				const inputExtensions = convertObjectToZuiLiterals(this._staticInputValues);
-				input = _bpinternal_zui.z.array(input.element.extend(inputExtensions));
-			} else input = convertObjectToZuiLiterals(this._staticInputValues);
-		}
-		return input;
+		const input = this._inputSchema ?? (this.input ? require_utils.fromJSONSchemaCompat(this.input) : _bpinternal_zui.z.any());
+		if (isEmpty(this._staticInputValues)) return input;
+		const shape = require_schema.schemaInput(input);
+		let overrides;
+		if (_bpinternal_zui.z.is.zuiObject(shape)) overrides = _bpinternal_zui.z.object(convertObjectToZuiLiterals(this._staticInputValues)).passthrough();
+		else if (_bpinternal_zui.z.is.zuiArray(shape)) overrides = _bpinternal_zui.z.array(_bpinternal_zui.z.object(convertObjectToZuiLiterals(this._staticInputValues)).passthrough());
+		else overrides = convertObjectToZuiLiterals(this._staticInputValues);
+		return overrides.pipe(input);
 	}
 	/**
-	* Gets the output schema for validation.
+	* Gets the output description as a promise schema. It is never used to parse tool results.
 	*
-	* @returns The Zui schema for output validation
+	* @returns The Zui schema used to describe likely output
 	* @internal
 	*/
 	get zOutput() {
@@ -290,7 +333,7 @@ var Tool = class Tool {
 	*/
 	rename(name) {
 		const before = this.name;
-		if (!require_utils.isValidIdentifier(name)) throw new Error(`Invalid name for tool ${name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
+		if (!require_utils.isValidIdentifier(name)) throw new require_errors.InvalidToolError(`Invalid name for tool ${name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
 		this.name = name;
 		this.aliases = require_uniq.uniq([name, ...this.aliases.map((alias) => alias === before ? name : alias)]);
 		return this;
@@ -353,33 +396,30 @@ var Tool = class Tool {
 	*/
 	clone(props = {}) {
 		try {
-			var _props$input, _props$output;
-			let zInput;
-			if (this.input) try {
-				zInput = _bpinternal_zui.transforms.fromJSONSchema(this.input);
-			} catch {
-				zInput = _bpinternal_zui.transforms.fromJSONSchemaLegacy(this.input);
-			}
-			let zOutput;
-			if (this.output) try {
-				zOutput = _bpinternal_zui.transforms.fromJSONSchema(this.output);
-			} catch {
-				zOutput = _bpinternal_zui.transforms.fromJSONSchemaLegacy(this.output);
-			}
+			const zInput = this._inputSchema ?? (this.input ? require_utils.fromJSONSchemaCompat(this.input) : void 0);
+			const zOutput = this._outputSchema ?? (this.output ? require_utils.fromJSONSchemaCompat(this.output) : void 0);
+			let input = zInput;
+			if (typeof props.input === "function") input = props.input(zInput);
+			else if (_bpinternal_zui.z.is.zuiType(props.input)) input = props.input;
+			let output = zOutput;
+			if (typeof props.output === "function") output = props.output(zOutput);
+			else if (_bpinternal_zui.z.is.zuiType(props.output)) output = props.output;
 			return new Tool({
 				name: props.name ?? this.name,
 				aliases: props.aliases ?? [...this.aliases],
 				description: props.description ?? this.description,
 				metadata: JSON.parse(JSON.stringify(props.metadata ?? this.metadata)),
-				input: typeof props.input === "function" ? (_props$input = props.input) === null || _props$input === void 0 ? void 0 : _props$input.call(props, zInput) : _bpinternal_zui.z.is.zuiType(props.input) ? props.input : zInput,
-				output: typeof props.output === "function" ? (_props$output = props.output) === null || _props$output === void 0 ? void 0 : _props$output.call(props, zOutput) : _bpinternal_zui.z.is.zuiType(props.output) ? props.output : zOutput,
+				input,
+				output,
 				handler: props.handler ?? this._handler,
 				retry: props.retry ?? this.retry
 			}).setStaticInputValues(props.staticInputValues ?? this._staticInputValues);
 		} catch (e) {
-			throw new Error(`Failed to clone tool "${this.name}": ${e}`);
+			throw new require_errors.InvalidToolError(`Failed to clone tool "${this.name}": ${e}`);
 		}
 	}
+	_inputSchema;
+	_outputSchema;
 	_handler;
 	/**
 	* Creates a new Tool instance.
@@ -388,7 +428,7 @@ var Tool = class Tool {
 	* @param props.name - Unique tool name (must be valid TypeScript identifier)
 	* @param props.description - Human-readable description for the LLM
 	* @param props.input - Zui/Zod schema for input validation (optional)
-	* @param props.output - Zui/Zod schema for output validation (optional)
+	* @param props.output - Schema describing likely raw output; never used for validation or normalization
 	* @param props.handler - Async function that implements the tool logic
 	* @param props.aliases - Alternative names for the tool (optional)
 	* @param props.metadata - Additional metadata for the tool (optional)
@@ -458,29 +498,32 @@ var Tool = class Tool {
 	* ```
 	*/
 	constructor(props) {
-		if (!require_utils.isValidIdentifier(props.name)) throw new Error(`Invalid name for tool ${props.name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
-		if (props.description !== void 0 && typeof props.description !== "string") throw new Error(`Invalid description for tool ${props.name}. Expected a string, but got type "${typeof props.description}"`);
-		if (props.metadata !== void 0 && typeof props.metadata !== "object") throw new Error(`Invalid metadata for tool ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
-		if (typeof props.handler !== "function") throw new Error(`Invalid handler for tool ${props.name}. Expected a function, but got type "${typeof props.handler}"`);
-		if (props.aliases !== void 0 && !Array.isArray(props.aliases)) throw new Error(`Invalid aliases for tool ${props.name}. Expected an array, but got type "${typeof props.aliases}"`);
-		if (props.aliases && props.aliases.some((alias) => !require_utils.isValidIdentifier(alias))) throw new Error(`Invalid aliases for tool ${props.name}. Expected an array of valid identifiers.`);
+		if (!props || typeof props !== "object" || Array.isArray(props)) throw new require_errors.InvalidToolError("Tool definition must be an object.");
+		if (!require_utils.isValidIdentifier(props.name)) throw new require_errors.InvalidToolError(`Invalid name for tool ${props.name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
+		if (props.description !== void 0 && typeof props.description !== "string") throw new require_errors.InvalidToolError(`Invalid description for tool ${props.name}. Expected a string, but got type "${typeof props.description}"`);
+		if (props.metadata !== void 0 && typeof props.metadata !== "object") throw new require_errors.InvalidToolError(`Invalid metadata for tool ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
+		if (typeof props.handler !== "function") throw new require_errors.InvalidToolError(`Invalid handler for tool ${props.name}. Expected a function, but got type "${typeof props.handler}"`);
+		if (props.aliases !== void 0 && !Array.isArray(props.aliases)) throw new require_errors.InvalidToolError(`Invalid aliases for tool ${props.name}. Expected an array, but got type "${typeof props.aliases}"`);
+		if (props.aliases && props.aliases.some((alias) => !require_utils.isValidIdentifier(alias))) throw new require_errors.InvalidToolError(`Invalid aliases for tool ${props.name}. Expected an array of valid identifiers.`);
 		if (typeof props.input !== "undefined") {
 			if (require_utils.isZuiSchema(props.input)) try {
-				this.input = _bpinternal_zui.transforms.toJSONSchema(props.input);
-			} catch {
-				this.input = _bpinternal_zui.transforms.toJSONSchemaLegacy(props.input);
+				this.input = require_schema.toModelSchema(props.input);
+				this._inputSchema = props.input;
+			} catch (cause) {
+				throw new require_errors.InvalidToolError(`Cannot describe input schema for tool ${props.name}: ${String(cause)}`, { cause });
 			}
 			else if (require_utils.isJsonSchema(props.input)) this.input = props.input;
-			else throw new Error(`Invalid input schema for tool ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.input}"`);
+			else throw new require_errors.InvalidToolError(`Invalid input schema for tool ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.input}"`);
 		}
 		if (typeof props.output !== "undefined") {
 			if (require_utils.isZuiSchema(props.output)) try {
-				this.output = _bpinternal_zui.transforms.toJSONSchema(props.output);
-			} catch {
-				this.output = _bpinternal_zui.transforms.toJSONSchemaLegacy(props.output);
+				this.output = require_schema.toModelSchema(props.output);
+				this._outputSchema = props.output;
+			} catch (cause) {
+				throw new require_errors.InvalidToolError(`Cannot describe output schema for tool ${props.name}: ${String(cause)}`, { cause });
 			}
 			else if (require_utils.isJsonSchema(props.output)) this.output = props.output;
-			else throw new Error(`Invalid output schema for tool ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.output}"`);
+			else throw new require_errors.InvalidToolError(`Invalid output schema for tool ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.output}"`);
 		}
 		this.name = props.name;
 		this.aliases = require_uniq.uniq([props.name, ...props.aliases ?? []]);
@@ -490,28 +533,10 @@ var Tool = class Tool {
 		this.setStaticInputValues(props.staticInputValues);
 		this.retry = props.retry;
 	}
-	async _executeHandler(input, ctx, chat, yieldedCount, setYieldedCount) {
-		const handler = this._handler(input, ctx);
-		if (!(typeof handler === "object" && handler !== null && "next" in handler)) return handler;
-		let yieldIndex = 0;
-		while (true) {
-			const { value, done } = await handler.next();
-			if (done) return value;
-			if (yieldIndex >= yieldedCount) {
-				var _chat$handler;
-				setYieldedCount(yieldIndex + 1);
-				await (chat === null || chat === void 0 || (_chat$handler = chat.handler) === null || _chat$handler === void 0 ? void 0 : _chat$handler.call(chat, value, {
-					iterationId: ctx.iterationId ?? ctx.callId,
-					id: `${ctx.callId}:yield-${yieldIndex}`
-				}));
-			}
-			yieldIndex++;
-		}
-	}
 	/**
 	* Executes the tool with the given input and context.
 	*
-	* This method handles input validation, retry logic, output validation, and error handling.
+	* This method parses inputs and handles retries. Output schemas are hints: results pass through unchanged.
 	* It's called internally by the LLMz execution engine when generated code calls the tool.
 	*
 	* @param input - Input data to pass to the tool handler
@@ -532,27 +557,43 @@ var Tool = class Tool {
 	*
 	* @internal This method is primarily used internally by the LLMz execution engine
 	*/
-	async execute(rawInput, ctx, chat) {
-		const input = this.zInput._def.typeName === "ZodObject" ? rawInput ?? {} : rawInput;
-		const pInput = this.zInput.safeParse(input);
-		if (!pInput.success) throw new Error(`Tool "${this.name}" received invalid input: ${pInput.error.message}`);
+	async execute(rawInput, ctx) {
+		var _ctx$onInput;
+		const schema = this.zInput;
+		const input = _bpinternal_zui.z.is.zuiObject(require_schema.schemaInput(schema)) ? rawInput ?? {} : rawInput;
+		const pInput = await require_schema.parseSchemaAsync(schema, input, `Tool "${this.name}" input`);
+		if (!pInput.success) {
+			const expectedInput = await require_typings.getTypings(this._inputSchema ?? schema);
+			const issues = pInput.error.issues.map(({ path, message }) => ({
+				path,
+				message
+			}));
+			throw new require_errors.ToolInputError(this.name, issues, expectedInput);
+		}
+		(_ctx$onInput = ctx.onInput) === null || _ctx$onInput === void 0 || _ctx$onInput.call(ctx, pInput.data);
 		let attempt = 0;
-		let yieldedCount = 0;
+		let lastError;
 		while (attempt < this.MAX_RETRIES) try {
-			const result = await this._executeHandler(pInput.data, ctx, chat, yieldedCount, (n) => {
-				yieldedCount = n;
+			const result = await this._handler(pInput.data, ctx);
+			const policy = require_truncate.isTruncated(result) ? result.$$truncate : void 0;
+			const output = require_truncate.unwrapTruncated(result);
+			if (!policy) return output;
+			return Promise.resolve(output).then((parsed) => {
+				var _ctx$onTruncation;
+				(_ctx$onTruncation = ctx.onTruncation) === null || _ctx$onTruncation === void 0 || _ctx$onTruncation.call(ctx, parsed, policy);
+				return parsed;
 			});
-			const pOutput = this.zOutput.safeParse(result);
-			return pOutput.success ? pOutput.data : result;
 		} catch (err) {
 			var _this$retry;
+			if (require_errors.isCriticalError(err) || require_errors.VMSignal.is(err)) throw err;
+			lastError = err;
 			if (!await ((_this$retry = this.retry) === null || _this$retry === void 0 ? void 0 : _this$retry.call(this, {
 				input: pInput.data,
 				attempt: ++attempt,
 				error: err
-			}))) throw err;
+			}))) throw require_errors.VMSignal.is(err) || require_errors.isLLMzError(err) ? err : new require_errors.ToolExecutionError(this.name, err);
 		}
-		throw new Error(`Tool "${this.name}" failed after ${this.MAX_RETRIES} attempts. Last error: ${JSON.stringify(input)}`);
+		throw new require_errors.ToolExecutionError(this.name, lastError);
 	}
 	/**
 	* Generates TypeScript type definitions for this tool.
@@ -570,6 +611,8 @@ var Tool = class Tool {
 		} catch {
 			input = _bpinternal_zui.transforms.fromJSONSchemaLegacy(this.input);
 		}
+		const originalInput = this._inputSchema && require_schema.schemaInput(this._inputSchema);
+		if (originalInput && (_bpinternal_zui.z.is.zuiVoid(originalInput) || _bpinternal_zui.z.is.zuiUndefined(originalInput))) input = originalInput;
 		let output;
 		if (!this.output || Object.keys(this.output).length === 0) output = _bpinternal_zui.z.void();
 		else try {
@@ -577,11 +620,20 @@ var Tool = class Tool {
 		} catch {
 			output = _bpinternal_zui.transforms.fromJSONSchemaLegacy(this.output);
 		}
-		if (input && _bpinternal_zui.z.is.zuiObject(input.naked()) && typeof this._staticInputValues === "object" && !require_isEmpty.isEmpty(this._staticInputValues)) {
+		if (input && _bpinternal_zui.z.is.zuiObject(input.naked()) && typeof this._staticInputValues === "object" && !isEmpty(this._staticInputValues)) {
 			const inputExtensions = convertObjectToZuiLiterals(this._staticInputValues);
 			input = input.extend(inputExtensions);
 		} else if (this._staticInputValues !== void 0) input = convertObjectToZuiLiterals(this._staticInputValues);
-		const fnType = _bpinternal_zui.z.function(input, _bpinternal_zui.z.promise(output)).title(this.name).describe(this.description ?? "");
+		const valueType = input === null || input === void 0 ? void 0 : input.naked();
+		let directType;
+		if (valueType) {
+			if (_bpinternal_zui.z.is.zuiString(valueType)) directType = "string";
+			else if (_bpinternal_zui.z.is.zuiNumber(valueType)) directType = "number";
+			else if (_bpinternal_zui.z.is.zuiBoolean(valueType)) directType = "boolean";
+			else if (_bpinternal_zui.z.is.zuiArray(valueType)) directType = "array";
+		}
+		const description = [this.description, directType && `Pass the ${directType} itself as the argument, not an object containing it.`].filter(Boolean).join("\n");
+		const fnType = _bpinternal_zui.z.function(input, _bpinternal_zui.z.promise(output)).title(this.name).describe(description);
 		return require_typings.getTypings(fnType, { declaration: true });
 	}
 	/**
@@ -625,7 +677,7 @@ var Tool = class Tool {
 		});
 	};
 	/**
-	* Converts the tool to its JSON representation.
+	* Serializes model-facing descriptions, not JavaScript validators. Use clone() to retain schema effects.
 	*
 	* @returns JSON representation of the Tool instance
 	*/

package/dist/tool.d.ts

@@ -1,7 +1,6 @@
 import { TypeOf, z, ZodType } from '@bpinternal/zui';
 import { JSONSchema7 } from 'json-schema';
-import { Chat } from './chat.js';
-import { RenderedComponent } from './component.js';
+import { type TruncationPolicy } from './truncate.js';
 import { Serializable } from './types.js';
 /**
  * Input parameters passed to tool retry functions.
@@ -49,8 +48,14 @@ type SmartPartial<T> = IsObject<T> extends true ? Partial<T> : T;
 type ToolCallContext = {
     /** Unique identifier for this specific tool call */
     callId: string;
-    /** Set by the runtime; standalone calls use callId as their message scope. */
+    /** Owning iteration, when run by LLMz. */
     iterationId?: string;
+    /** Native run_javascript call owning this invocation, when run by LLMz. */
+    nativeCallId?: string;
+    /** @internal Report the parsed argument without evaluating its effects again for traces. */
+    onInput?: (input: unknown) => void;
+    /** @internal Capture display policy while keeping the returned value ordinary JavaScript data. */
+    onTruncation?: (value: unknown, policy: TruncationPolicy) => void;
 };
 export declare namespace Tool {
     type JSON = {
@@ -73,7 +78,7 @@ export declare namespace Tool {
  *
  * ## Key Features
  * - **Type Safety**: Full TypeScript inference with Zui/Zod schema validation
- * - **Input/Output Validation**: Automatic validation of inputs and outputs against schemas
+ * - **Input Validation**: Parse inputs through their original schema; output schemas are documentation only
  * - **Retry Logic**: Built-in retry mechanisms with custom retry functions
  * - **Static Values**: Pre-configure parameters that won't change between calls
  * - **Tool Cloning**: Create variations of existing tools with modified behavior
@@ -200,7 +205,7 @@ export declare namespace Tool {
  *
  * Tools automatically handle:
  * - **Input validation**: Invalid inputs throw descriptive errors
- * - **Output validation**: Outputs are validated but invalid outputs are still returned
+ * - **Output hints**: Schemas describe likely outputs; results are never parsed or rejected
  * - **Handler errors**: Exceptions in handlers are caught and can trigger retries
  * - **Type coercion**: Basic type coercion where possible
  *
@@ -211,7 +216,9 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
     aliases: string[];
     description?: string;
     metadata: Record<string, unknown>;
+    /** Model-facing input description; zInput retains the original validator. */
     input?: JSONSchema7;
+    /** Expected raw output shape, used for documentation only. */
     output?: JSONSchema7;
     retry?: ToolRetryFn<TypeOf<I>>;
     MAX_RETRIES: number;
@@ -256,7 +263,7 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
      * const unrestricted = restrictedTool.setStaticInputValues(null)
      * ```
      */
-    setStaticInputValues(values: SmartPartial<TypeOf<I>>): this;
+    setStaticInputValues(values: SmartPartial<z.input<I>>): this;
     /**
      * Gets the computed input schema with static values applied.
      *
@@ -268,9 +275,9 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
      */
     get zInput(): ZodType<any, z.ZodTypeDef, any>;
     /**
-     * Gets the output schema for validation.
+     * Gets the output description as a promise schema. It is never used to parse tool results.
      *
-     * @returns The Zui schema for output validation
+     * @returns The Zui schema used to describe likely output
      * @internal
      */
     get zOutput(): z.ZodPromise<ZodType<any, z.ZodTypeDef, any>>;
@@ -352,10 +359,12 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
         metadata?: Record<string, unknown>;
         input: IX | ((original: I | undefined) => IX);
         output: OX | ((original: O | undefined) => OX);
-        staticInputValues?: SmartPartial<TypeOf<IX>>;
-        handler: (args: TypeOf<IX>, ctx: ToolCallContext) => AsyncGenerator<RenderedComponent, TypeOf<OX>> | Promise<TypeOf<OX>>;
+        staticInputValues?: SmartPartial<z.input<IX>>;
+        handler: (args: TypeOf<IX>, ctx: ToolCallContext) => Promise<unknown>;
         retry: ToolRetryFn<TypeOf<IX>>;
     }>): Tool<IX, OX>;
+    private _inputSchema?;
+    private _outputSchema?;
     private _handler;
     /**
      * Creates a new Tool instance.
@@ -364,7 +373,7 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
      * @param props.name - Unique tool name (must be valid TypeScript identifier)
      * @param props.description - Human-readable description for the LLM
      * @param props.input - Zui/Zod schema for input validation (optional)
-     * @param props.output - Zui/Zod schema for output validation (optional)
+     * @param props.output - Schema describing likely raw output; never used for validation or normalization
      * @param props.handler - Async function that implements the tool logic
      * @param props.aliases - Alternative names for the tool (optional)
      * @param props.metadata - Additional metadata for the tool (optional)
@@ -440,15 +449,14 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
         metadata?: Record<string, unknown>;
         input?: I;
         output?: O;
-        staticInputValues?: Partial<TypeOf<I>>;
-        handler: (args: TypeOf<I>, ctx: ToolCallContext) => AsyncGenerator<RenderedComponent, TypeOf<O>> | Promise<TypeOf<O>>;
+        staticInputValues?: SmartPartial<z.input<I>>;
+        handler: (args: TypeOf<I>, ctx: ToolCallContext) => Promise<unknown>;
         retry?: ToolRetryFn<TypeOf<I>>;
     });
-    private _executeHandler;
     /**
      * Executes the tool with the given input and context.
      *
-     * This method handles input validation, retry logic, output validation, and error handling.
+     * This method parses inputs and handles retries. Output schemas are hints: results pass through unchanged.
      * It's called internally by the LLMz execution engine when generated code calls the tool.
      *
      * @param input - Input data to pass to the tool handler
@@ -469,7 +477,7 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
      *
      * @internal This method is primarily used internally by the LLMz execution engine
      */
-    execute(rawInput: TypeOf<I>, ctx: ToolCallContext, chat?: Chat): Promise<TypeOf<O>>;
+    execute(rawInput: z.input<I>, ctx: ToolCallContext): Promise<z.input<O>>;
     /**
      * Generates TypeScript type definitions for this tool.
      *
@@ -511,7 +519,7 @@ export declare class Tool<I extends z.ZodType = z.ZodType, O extends z.ZodType =
      */
     static withUniqueNames: (tools: Tool<any, any>[]) => Tool<any, any>[];
     /**
-     * Converts the tool to its JSON representation.
+     * Serializes model-facing descriptions, not JavaScript validators. Use clone() to retain schema effects.
      *
      * @returns JSON representation of the Tool instance
      */

package/dist/truncate-BEKbdo3t.js

@@ -0,0 +1,79 @@
+import { b as InvalidConfigurationError } from "./errors-Crk5P8jo.js";
+//#region src/truncate.ts
+const TRUNCATE_SIGNATURE = "llmz.truncate.v1";
+const DEFAULT_TOOL_RESULT_MAX_TOKENS = 2e3;
+/** Sets a display budget without truncating or changing the underlying value. */
+function truncate({ value, maxTokens, preserve = "top" }) {
+	if (!Number.isSafeInteger(maxTokens) || maxTokens < 0) throw new InvalidConfigurationError("maxTokens must be a finite nonnegative integer");
+	if (preserve !== "top" && preserve !== "bottom" && preserve !== "both") throw new InvalidConfigurationError("preserve must be \"top\", \"bottom\", or \"both\"");
+	return Object.freeze({
+		$$truncate: Object.freeze({
+			signature: TRUNCATE_SIGNATURE,
+			maxTokens,
+			preserve
+		}),
+		value
+	});
+}
+function ownValue(value, key) {
+	const descriptor = Object.getOwnPropertyDescriptor(value, key);
+	return descriptor && "value" in descriptor ? descriptor.value : void 0;
+}
+function isTruncated(value) {
+	if (!value || typeof value !== "object") return false;
+	const policy = ownValue(value, "$$truncate");
+	if (!policy || typeof policy !== "object" || !Object.hasOwn(value, "value")) return false;
+	const signature = ownValue(policy, "signature");
+	const maxTokens = ownValue(policy, "maxTokens");
+	const preserve = ownValue(policy, "preserve");
+	const valueDescriptor = Object.getOwnPropertyDescriptor(value, "value");
+	return signature === TRUNCATE_SIGNATURE && typeof maxTokens === "number" && Number.isSafeInteger(maxTokens) && maxTokens >= 0 && (preserve === "top" || preserve === "bottom" || preserve === "both") && !!valueDescriptor && "value" in valueDescriptor;
+}
+function isContainer(value) {
+	if (!value || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return Array.isArray(value) || prototype === Object.prototype || prototype === null;
+}
+function unwrapTruncated(value) {
+	let underlying = value;
+	const rootWrappers = /* @__PURE__ */ new WeakSet();
+	while (isTruncated(underlying)) {
+		if (rootWrappers.has(underlying)) throw new InvalidConfigurationError("Circular truncation wrappers cannot be unwrapped");
+		rootWrappers.add(underlying);
+		underlying = underlying.value;
+	}
+	const visited = /* @__PURE__ */ new WeakSet();
+	function containsWrapper(current) {
+		if (isTruncated(current)) return true;
+		if (!isContainer(current) || visited.has(current)) return false;
+		visited.add(current);
+		for (const key of Reflect.ownKeys(current)) if (containsWrapper(ownValue(current, key))) return true;
+		return false;
+	}
+	if (!containsWrapper(underlying)) return underlying;
+	const copies = /* @__PURE__ */ new WeakMap();
+	const wrappers = /* @__PURE__ */ new WeakSet();
+	function unwrap(current) {
+		if (current && typeof current === "object" && copies.has(current)) return copies.get(current);
+		if (isTruncated(current)) {
+			if (wrappers.has(current)) throw new InvalidConfigurationError("Circular truncation wrappers cannot be unwrapped");
+			wrappers.add(current);
+			const result = unwrap(current.value);
+			wrappers.delete(current);
+			copies.set(current, result);
+			return result;
+		}
+		if (!isContainer(current)) return current;
+		const copy = Array.isArray(current) ? new Array(current.length) : Object.create(Object.getPrototypeOf(current));
+		copies.set(current, copy);
+		for (const key of Reflect.ownKeys(current)) {
+			const descriptor = Object.getOwnPropertyDescriptor(current, key);
+			if ("value" in descriptor) descriptor.value = unwrap(descriptor.value);
+			Object.defineProperty(copy, key, descriptor);
+		}
+		return copy;
+	}
+	return unwrap(underlying);
+}
+//#endregion
+export { unwrapTruncated as i, isTruncated as n, truncate as r, DEFAULT_TOOL_RESULT_MAX_TOKENS as t };