llmz 0.9.0 → 1.0.2

package/dist/{tool-Bv8N4IPj.js → tool-DstssiAs.js}

@@ -1,9 +1,59 @@
-import { n as __exportAll } from "./rolldown-runtime-EAsCxrDo.js";
-import { t as uniq } from "./uniq-BYQ7GWwb.js";
-import { c as isJsonSchema, l as isValidIdentifier, r as fromJSONSchemaCompat, u as isZuiSchema } from "./utils-UBeAFeEI.js";
-import { t as isEmpty } from "./isEmpty-BhJRCqIF.js";
-import { t as getTypings } from "./typings-CrBa7Tyy.js";
+import { F as isBuffer, I as isArguments, L as isPrototype, M as isTypedArray, R as isArrayLike, U as isArray, Y as __exportAll, c as isValidIdentifier, j as baseKeys, l as isZuiSchema, n as fromJSONSchemaCompat, s as isJsonSchema, x as _getTag_default } from "./utils-BOFzb8Ok.js";
+import { E as InvalidToolError, H as isCriticalError, L as ToolExecutionError, R as ToolInputError, U as isLLMzError, r as VMSignal } from "./errors-Crk5P8jo.js";
+import { t as uniq } from "./uniq-DfUeSNaX.js";
+import { i as toModelSchema, r as schemaInput, t as parseSchemaAsync } from "./schema-GE4ISPCR.js";
+import { i as unwrapTruncated, n as isTruncated } from "./truncate-BEKbdo3t.js";
+import { t as getTypings } from "./typings-BEVDvtuk.js";
 import { transforms, z } from "@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 (isArrayLike(value) && (isArray(value) || typeof value == "string" || typeof value.splice == "function" || isBuffer(value) || isTypedArray(value) || isArguments(value))) return !value.length;
+	var tag = _getTag_default(value);
+	if (tag == mapTag || tag == setTag) return !value.size;
+	if (isPrototype(value)) return !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 z.literal(obj).catch(() => obj);
@@ -37,7 +87,7 @@ var tool_exports = /* @__PURE__ */ __exportAll({ Tool: () => 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
@@ -164,7 +214,7 @@ var tool_exports = /* @__PURE__ */ __exportAll({ Tool: () => 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
 *
@@ -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 ? fromJSONSchemaCompat(this.input) : z.any();
-		if (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 (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 (z.is.zuiObject(input) && typeof values !== "object") throw new InvalidToolError(`Invalid static input values for tool ${this.name}. Expected an object, but got type "${typeof values}"`);
+		if (z.is.zuiArray(input) && !Array.isArray(values)) throw new 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 = transforms.fromJSONSchema(this.input);
-		} catch {
-			input = transforms.fromJSONSchemaLegacy(this.input);
-		}
-		else input = z.any();
-		if (!isEmpty(this._staticInputValues)) {
-			if (z.is.zuiObject(input)) {
-				const inputExtensions = convertObjectToZuiLiterals(this._staticInputValues);
-				input = input.extend(inputExtensions);
-			} else if (z.is.zuiArray(input)) {
-				const inputExtensions = convertObjectToZuiLiterals(this._staticInputValues);
-				input = z.array(input.element.extend(inputExtensions));
-			} else input = convertObjectToZuiLiterals(this._staticInputValues);
-		}
-		return input;
+		const input = this._inputSchema ?? (this.input ? fromJSONSchemaCompat(this.input) : z.any());
+		if (isEmpty(this._staticInputValues)) return input;
+		const shape = schemaInput(input);
+		let overrides;
+		if (z.is.zuiObject(shape)) overrides = z.object(convertObjectToZuiLiterals(this._staticInputValues)).passthrough();
+		else if (z.is.zuiArray(shape)) overrides = z.array(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 (!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 (!isValidIdentifier(name)) throw new 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 = 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 = transforms.fromJSONSchema(this.input);
-			} catch {
-				zInput = transforms.fromJSONSchemaLegacy(this.input);
-			}
-			let zOutput;
-			if (this.output) try {
-				zOutput = transforms.fromJSONSchema(this.output);
-			} catch {
-				zOutput = transforms.fromJSONSchemaLegacy(this.output);
-			}
+			const zInput = this._inputSchema ?? (this.input ? fromJSONSchemaCompat(this.input) : void 0);
+			const zOutput = this._outputSchema ?? (this.output ? fromJSONSchemaCompat(this.output) : void 0);
+			let input = zInput;
+			if (typeof props.input === "function") input = props.input(zInput);
+			else if (z.is.zuiType(props.input)) input = props.input;
+			let output = zOutput;
+			if (typeof props.output === "function") output = props.output(zOutput);
+			else if (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) : 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) : 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 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 (!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) => !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 InvalidToolError("Tool definition must be an object.");
+		if (!isValidIdentifier(props.name)) throw new 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 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 InvalidToolError(`Invalid metadata for tool ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
+		if (typeof props.handler !== "function") throw new 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 InvalidToolError(`Invalid aliases for tool ${props.name}. Expected an array, but got type "${typeof props.aliases}"`);
+		if (props.aliases && props.aliases.some((alias) => !isValidIdentifier(alias))) throw new InvalidToolError(`Invalid aliases for tool ${props.name}. Expected an array of valid identifiers.`);
 		if (typeof props.input !== "undefined") {
 			if (isZuiSchema(props.input)) try {
-				this.input = transforms.toJSONSchema(props.input);
-			} catch {
-				this.input = transforms.toJSONSchemaLegacy(props.input);
+				this.input = toModelSchema(props.input);
+				this._inputSchema = props.input;
+			} catch (cause) {
+				throw new InvalidToolError(`Cannot describe input schema for tool ${props.name}: ${String(cause)}`, { cause });
 			}
 			else if (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 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 (isZuiSchema(props.output)) try {
-				this.output = transforms.toJSONSchema(props.output);
-			} catch {
-				this.output = transforms.toJSONSchemaLegacy(props.output);
+				this.output = toModelSchema(props.output);
+				this._outputSchema = props.output;
+			} catch (cause) {
+				throw new InvalidToolError(`Cannot describe output schema for tool ${props.name}: ${String(cause)}`, { cause });
 			}
 			else if (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 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 = 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 = z.is.zuiObject(schemaInput(schema)) ? rawInput ?? {} : rawInput;
+		const pInput = await parseSchemaAsync(schema, input, `Tool "${this.name}" input`);
+		if (!pInput.success) {
+			const expectedInput = await getTypings(this._inputSchema ?? schema);
+			const issues = pInput.error.issues.map(({ path, message }) => ({
+				path,
+				message
+			}));
+			throw new 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 = isTruncated(result) ? result.$$truncate : void 0;
+			const output = 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 (isCriticalError(err) || 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 VMSignal.is(err) || isLLMzError(err) ? err : new ToolExecutionError(this.name, err);
 		}
-		throw new Error(`Tool "${this.name}" failed after ${this.MAX_RETRIES} attempts. Last error: ${JSON.stringify(input)}`);
+		throw new ToolExecutionError(this.name, lastError);
 	}
 	/**
 	* Generates TypeScript type definitions for this tool.
@@ -570,6 +611,8 @@ var Tool = class Tool {
 		} catch {
 			input = transforms.fromJSONSchemaLegacy(this.input);
 		}
+		const originalInput = this._inputSchema && schemaInput(this._inputSchema);
+		if (originalInput && (z.is.zuiVoid(originalInput) || z.is.zuiUndefined(originalInput))) input = originalInput;
 		let output;
 		if (!this.output || Object.keys(this.output).length === 0) output = z.void();
 		else try {
@@ -581,7 +624,16 @@ var Tool = class Tool {
 			const inputExtensions = convertObjectToZuiLiterals(this._staticInputValues);
 			input = input.extend(inputExtensions);
 		} else if (this._staticInputValues !== void 0) input = convertObjectToZuiLiterals(this._staticInputValues);
-		const fnType = z.function(input, 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 (z.is.zuiString(valueType)) directType = "string";
+			else if (z.is.zuiNumber(valueType)) directType = "number";
+			else if (z.is.zuiBoolean(valueType)) directType = "boolean";
+			else if (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 = z.function(input, z.promise(output)).title(this.name).describe(description);
 		return 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
 	*/