llmz 0.9.0 → 1.0.2

package/dist/{exit-DUM96DN1.cjs → exit-BOtKWPuT.cjs}

@@ -1,16 +1,16 @@
-const require_compiler = require("./compiler-C-OI9sim.cjs");
-const require_uniq = require("./uniq-G872RWmE.cjs");
-const require_utils = require("./utils-3ESwP3yg.cjs");
-let _bpinternal_zui = require("@bpinternal/zui");
+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");
 //#region src/exit.ts
-var exit_exports = /* @__PURE__ */ require_compiler.__exportAll({ Exit: () => Exit });
+var exit_exports = /* @__PURE__ */ require_utils.__exportAll({ Exit: () => Exit });
 /**
 * Defines how LLMz agent execution can terminate.
 *
 * Exits are the primary mechanism for controlling how and when agent execution completes.
 * They define the possible outcomes of an execution and provide type-safe result handling.
-* When an agent calls `return { action: 'exit_name', ...data }`, the execution terminates
-* with the corresponding Exit.
+* The model returns `exit(name, payload)` from JavaScript to finish with a validated
+* payload. Ordinary returned values remain nonterminal inspection results.
 *
 * ## Core Concepts
 *
@@ -24,7 +24,7 @@ var exit_exports = /* @__PURE__ */ require_compiler.__exportAll({ Exit: () => Ex
 * **Flow Control**: Different exits allow for different execution paths and result
 * handling, enabling complex decision-making and branching logic.
 *
-* **Built-in vs Custom**: LLMz provides built-in exits (ThinkExit, ListenExit, DefaultExit)
+* **Built-in vs Custom**: LLMz provides built-in exits (ListenExit, DefaultExit)
 * for common patterns, while custom exits enable domain-specific termination logic.
 *
 * ## Usage Patterns
@@ -39,7 +39,7 @@ var exit_exports = /* @__PURE__ */ require_compiler.__exportAll({ Exit: () => Ex
 *   description: 'When the user wants to exit the program',
 * })
 *
-* // Agent usage: return { action: 'exit' }
+* // Inside run_javascript: return exit('exit')
 *
 * // Result handling
 * if (result.is(exit)) {
@@ -63,7 +63,8 @@ var exit_exports = /* @__PURE__ */ require_compiler.__exportAll({ Exit: () => Ex
 *   }),
 * })
 *
-* // Agent usage: return { action: 'escalation', reason: 'Technical issue', details: '...' }
+* // Inside run_javascript:
+* // return exit('escalation', { reason: 'Technical issue', details: '...' })
 *
 * // Type-safe result handling
 * if (result.is(escalation)) {
@@ -113,7 +114,7 @@ var exit_exports = /* @__PURE__ */ require_compiler.__exportAll({ Exit: () => Ex
 *
 * ### Exit Aliases
 *
-* Multiple names for the same exit:
+* Alternative names for the same exit:
 *
 * ```typescript
 * const exit = new Exit({
@@ -122,7 +123,8 @@ var exit_exports = /* @__PURE__ */ require_compiler.__exportAll({ Exit: () => Ex
 *   description: 'Task completed successfully',
 * })
 *
-* // Agent can use any alias: return { action: 'done' } or { action: 'finished' }
+* // JavaScript can return exit('complete'), exit('done'), or another registered alias.
+* // These all select the same exit without creating additional native tools.
 * ```
 *
 * ### Exit Metadata for Orchestration
@@ -200,27 +202,27 @@ var exit_exports = /* @__PURE__ */ require_compiler.__exportAll({ Exit: () => Ex
 * @template T - The type of data this exit returns (inferred from schema)
 *
 * @see {@link ExecutionResult} For result handling
-* @see {@link ThinkExit} Built-in thinking exit
 * @see {@link ListenExit} Built-in chat listening exit
 * @see {@link DefaultExit} Built-in completion exit
 */
 var Exit = class Exit {
-	/** The primary name of the exit (used in return statements) */
+	/** The primary name of the exit (used by its native exit tool) */
 	name;
-	/** Alternative names that can be used to reference this exit */
+	/** Host-side aliases; the native tool uses only the primary name */
 	aliases = [];
 	/** Human-readable description of when this exit should be used */
 	description;
 	/** Additional metadata for orchestration and custom logic */
 	metadata;
-	/** JSON Schema for validating exit result data */
+	/** Model-facing payload description. The original validator is retained in zSchema. */
 	schema;
+	_schema;
 	/**
-	* Returns the Zod schema equivalent of the JSON schema (if available).
+	* Returns the original runtime validator, preserving transforms and refinements.
 	* Used internally for validation and type inference.
 	*/
 	get zSchema() {
-		return this.schema ? require_utils.fromJSONSchemaCompat(this.schema) : void 0;
+		return this._schema ?? (this.schema ? require_utils.fromJSONSchemaCompat(this.schema) : void 0);
 	}
 	/**
 	* Renames the exit and updates aliases accordingly.
@@ -237,7 +239,7 @@ var Exit = class Exit {
 	*/
 	rename(name) {
 		const before = this.name;
-		if (!require_utils.isValidIdentifier(name)) throw new Error(`Invalid name for exit ${name}. An exit 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.InvalidExitError(`Invalid name for exit ${name}. An exit 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;
@@ -292,7 +294,7 @@ var Exit = class Exit {
 		return result.exit instanceof Exit && this.name === result.exit.name;
 	}
 	/**
-	* Serializes this exit to a JSON-compatible object.
+	* Serializes the model-facing description. JavaScript validators cannot be serialized; use clone() to retain them.
 	*
 	* @returns JSON representation of the exit
 	*
@@ -368,15 +370,23 @@ var Exit = class Exit {
 	* ```
 	*/
 	constructor(props) {
-		if (!require_utils.isValidIdentifier(props.name)) throw new Error(`Invalid name for exit ${props.name}. A exit name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
-		if (typeof props.description !== "string" || props.description.trim().length === 0) throw new Error(`Invalid description for exit ${props.name}. Expected a non-empty string, but got type "${typeof props.description}"`);
-		if (props.metadata !== void 0 && typeof props.metadata !== "object") throw new Error(`Invalid metadata for exit ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
-		if (props.aliases !== void 0 && !Array.isArray(props.aliases)) throw new Error(`Invalid aliases for exit ${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 exit ${props.name}. Expected an array of valid identifiers.`);
+		if (!props || typeof props !== "object" || Array.isArray(props)) throw new require_errors.InvalidExitError("Exit definition must be an object.");
+		if (!require_utils.isValidIdentifier(props.name)) throw new require_errors.InvalidExitError(`Invalid name for exit ${props.name}. A exit name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
+		if (typeof props.description !== "string" || props.description.trim().length === 0) throw new require_errors.InvalidExitError(`Invalid description for exit ${props.name}. Expected a non-empty string, but got type "${typeof props.description}"`);
+		if (props.metadata !== void 0 && typeof props.metadata !== "object") throw new require_errors.InvalidExitError(`Invalid metadata for exit ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
+		if (props.aliases !== void 0 && !Array.isArray(props.aliases)) throw new require_errors.InvalidExitError(`Invalid aliases for exit ${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.InvalidExitError(`Invalid aliases for exit ${props.name}. Expected an array of valid identifiers.`);
 		if (typeof props.schema !== "undefined") {
-			if (require_utils.isZuiSchema(props.schema)) this.schema = _bpinternal_zui.transforms.toJSONSchemaLegacy(props.schema);
-			else if (require_utils.isJsonSchema(props.schema)) this.schema = props.schema;
-			else throw new Error(`Invalid input schema for exit ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.schema}"`);
+			if (require_utils.isZuiSchema(props.schema)) {
+				if (["ZodUndefined", "ZodVoid"].includes(props.schema._def.typeName)) throw new require_errors.InvalidExitError(`Exit ${props.name} must use a JSON-compatible payload schema. Omit schema for an exit without data, or use z.null() for an explicit null payload.`);
+				try {
+					this.schema = require_schema.toModelSchema(props.schema);
+					this._schema = props.schema;
+				} catch (cause) {
+					throw new require_errors.InvalidExitError(`Cannot describe schema for exit ${props.name}: ${String(cause)}`, { cause });
+				}
+			} else if (require_utils.isJsonSchema(props.schema)) this.schema = props.schema;
+			else throw new require_errors.InvalidExitError(`Invalid input schema for exit ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.schema}"`);
 		}
 		this.name = props.name;
 		this.aliases = require_uniq.uniq([props.name, ...props.aliases ?? []]);

package/dist/{exit-CDdxDBRT.js → exit-DMPwCSba.js}

@@ -1,7 +1,7 @@
-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 { transforms } from "@bpinternal/zui";
+import { Y as __exportAll, c as isValidIdentifier, l as isZuiSchema, n as fromJSONSchemaCompat, s as isJsonSchema } from "./utils-BOFzb8Ok.js";
+import { S as InvalidExitError } from "./errors-Crk5P8jo.js";
+import { t as uniq } from "./uniq-DfUeSNaX.js";
+import { i as toModelSchema } from "./schema-GE4ISPCR.js";
 //#region src/exit.ts
 var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 /**
@@ -9,8 +9,8 @@ var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 *
 * Exits are the primary mechanism for controlling how and when agent execution completes.
 * They define the possible outcomes of an execution and provide type-safe result handling.
-* When an agent calls `return { action: 'exit_name', ...data }`, the execution terminates
-* with the corresponding Exit.
+* The model returns `exit(name, payload)` from JavaScript to finish with a validated
+* payload. Ordinary returned values remain nonterminal inspection results.
 *
 * ## Core Concepts
 *
@@ -24,7 +24,7 @@ var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 * **Flow Control**: Different exits allow for different execution paths and result
 * handling, enabling complex decision-making and branching logic.
 *
-* **Built-in vs Custom**: LLMz provides built-in exits (ThinkExit, ListenExit, DefaultExit)
+* **Built-in vs Custom**: LLMz provides built-in exits (ListenExit, DefaultExit)
 * for common patterns, while custom exits enable domain-specific termination logic.
 *
 * ## Usage Patterns
@@ -39,7 +39,7 @@ var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 *   description: 'When the user wants to exit the program',
 * })
 *
-* // Agent usage: return { action: 'exit' }
+* // Inside run_javascript: return exit('exit')
 *
 * // Result handling
 * if (result.is(exit)) {
@@ -63,7 +63,8 @@ var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 *   }),
 * })
 *
-* // Agent usage: return { action: 'escalation', reason: 'Technical issue', details: '...' }
+* // Inside run_javascript:
+* // return exit('escalation', { reason: 'Technical issue', details: '...' })
 *
 * // Type-safe result handling
 * if (result.is(escalation)) {
@@ -113,7 +114,7 @@ var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 *
 * ### Exit Aliases
 *
-* Multiple names for the same exit:
+* Alternative names for the same exit:
 *
 * ```typescript
 * const exit = new Exit({
@@ -122,7 +123,8 @@ var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 *   description: 'Task completed successfully',
 * })
 *
-* // Agent can use any alias: return { action: 'done' } or { action: 'finished' }
+* // JavaScript can return exit('complete'), exit('done'), or another registered alias.
+* // These all select the same exit without creating additional native tools.
 * ```
 *
 * ### Exit Metadata for Orchestration
@@ -200,27 +202,27 @@ var exit_exports = /* @__PURE__ */ __exportAll({ Exit: () => Exit });
 * @template T - The type of data this exit returns (inferred from schema)
 *
 * @see {@link ExecutionResult} For result handling
-* @see {@link ThinkExit} Built-in thinking exit
 * @see {@link ListenExit} Built-in chat listening exit
 * @see {@link DefaultExit} Built-in completion exit
 */
 var Exit = class Exit {
-	/** The primary name of the exit (used in return statements) */
+	/** The primary name of the exit (used by its native exit tool) */
 	name;
-	/** Alternative names that can be used to reference this exit */
+	/** Host-side aliases; the native tool uses only the primary name */
 	aliases = [];
 	/** Human-readable description of when this exit should be used */
 	description;
 	/** Additional metadata for orchestration and custom logic */
 	metadata;
-	/** JSON Schema for validating exit result data */
+	/** Model-facing payload description. The original validator is retained in zSchema. */
 	schema;
+	_schema;
 	/**
-	* Returns the Zod schema equivalent of the JSON schema (if available).
+	* Returns the original runtime validator, preserving transforms and refinements.
 	* Used internally for validation and type inference.
 	*/
 	get zSchema() {
-		return this.schema ? fromJSONSchemaCompat(this.schema) : void 0;
+		return this._schema ?? (this.schema ? fromJSONSchemaCompat(this.schema) : void 0);
 	}
 	/**
 	* Renames the exit and updates aliases accordingly.
@@ -237,7 +239,7 @@ var Exit = class Exit {
 	*/
 	rename(name) {
 		const before = this.name;
-		if (!isValidIdentifier(name)) throw new Error(`Invalid name for exit ${name}. An exit 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 InvalidExitError(`Invalid name for exit ${name}. An exit 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;
@@ -292,7 +294,7 @@ var Exit = class Exit {
 		return result.exit instanceof Exit && this.name === result.exit.name;
 	}
 	/**
-	* Serializes this exit to a JSON-compatible object.
+	* Serializes the model-facing description. JavaScript validators cannot be serialized; use clone() to retain them.
 	*
 	* @returns JSON representation of the exit
 	*
@@ -368,15 +370,23 @@ var Exit = class Exit {
 	* ```
 	*/
 	constructor(props) {
-		if (!isValidIdentifier(props.name)) throw new Error(`Invalid name for exit ${props.name}. A exit name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
-		if (typeof props.description !== "string" || props.description.trim().length === 0) throw new Error(`Invalid description for exit ${props.name}. Expected a non-empty string, but got type "${typeof props.description}"`);
-		if (props.metadata !== void 0 && typeof props.metadata !== "object") throw new Error(`Invalid metadata for exit ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
-		if (props.aliases !== void 0 && !Array.isArray(props.aliases)) throw new Error(`Invalid aliases for exit ${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 exit ${props.name}. Expected an array of valid identifiers.`);
+		if (!props || typeof props !== "object" || Array.isArray(props)) throw new InvalidExitError("Exit definition must be an object.");
+		if (!isValidIdentifier(props.name)) throw new InvalidExitError(`Invalid name for exit ${props.name}. A exit name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
+		if (typeof props.description !== "string" || props.description.trim().length === 0) throw new InvalidExitError(`Invalid description for exit ${props.name}. Expected a non-empty string, but got type "${typeof props.description}"`);
+		if (props.metadata !== void 0 && typeof props.metadata !== "object") throw new InvalidExitError(`Invalid metadata for exit ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
+		if (props.aliases !== void 0 && !Array.isArray(props.aliases)) throw new InvalidExitError(`Invalid aliases for exit ${props.name}. Expected an array, but got type "${typeof props.aliases}"`);
+		if (props.aliases && props.aliases.some((alias) => !isValidIdentifier(alias))) throw new InvalidExitError(`Invalid aliases for exit ${props.name}. Expected an array of valid identifiers.`);
 		if (typeof props.schema !== "undefined") {
-			if (isZuiSchema(props.schema)) this.schema = transforms.toJSONSchemaLegacy(props.schema);
-			else if (isJsonSchema(props.schema)) this.schema = props.schema;
-			else throw new Error(`Invalid input schema for exit ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.schema}"`);
+			if (isZuiSchema(props.schema)) {
+				if (["ZodUndefined", "ZodVoid"].includes(props.schema._def.typeName)) throw new InvalidExitError(`Exit ${props.name} must use a JSON-compatible payload schema. Omit schema for an exit without data, or use z.null() for an explicit null payload.`);
+				try {
+					this.schema = toModelSchema(props.schema);
+					this._schema = props.schema;
+				} catch (cause) {
+					throw new InvalidExitError(`Cannot describe schema for exit ${props.name}: ${String(cause)}`, { cause });
+				}
+			} else if (isJsonSchema(props.schema)) this.schema = props.schema;
+			else throw new InvalidExitError(`Invalid input schema for exit ${props.name}. Expected a ZodType or JSONSchema, but got type "${typeof props.schema}"`);
 		}
 		this.name = props.name;
 		this.aliases = uniq([props.name, ...props.aliases ?? []]);

package/dist/exit.d.ts

@@ -1,3 +1,4 @@
+import { z } from '@bpinternal/zui';
 import { JSONSchema7 } from 'json-schema';
 import { Serializable, ZuiType } from './types.js';
 /**
@@ -25,8 +26,8 @@ export declare namespace Exit {
  *
  * Exits are the primary mechanism for controlling how and when agent execution completes.
  * They define the possible outcomes of an execution and provide type-safe result handling.
- * When an agent calls `return { action: 'exit_name', ...data }`, the execution terminates
- * with the corresponding Exit.
+ * The model returns `exit(name, payload)` from JavaScript to finish with a validated
+ * payload. Ordinary returned values remain nonterminal inspection results.
  *
  * ## Core Concepts
  *
@@ -40,7 +41,7 @@ export declare namespace Exit {
  * **Flow Control**: Different exits allow for different execution paths and result
  * handling, enabling complex decision-making and branching logic.
  *
- * **Built-in vs Custom**: LLMz provides built-in exits (ThinkExit, ListenExit, DefaultExit)
+ * **Built-in vs Custom**: LLMz provides built-in exits (ListenExit, DefaultExit)
  * for common patterns, while custom exits enable domain-specific termination logic.
  *
  * ## Usage Patterns
@@ -55,7 +56,7 @@ export declare namespace Exit {
  *   description: 'When the user wants to exit the program',
  * })
  *
- * // Agent usage: return { action: 'exit' }
+ * // Inside run_javascript: return exit('exit')
  *
  * // Result handling
  * if (result.is(exit)) {
@@ -79,7 +80,8 @@ export declare namespace Exit {
  *   }),
  * })
  *
- * // Agent usage: return { action: 'escalation', reason: 'Technical issue', details: '...' }
+ * // Inside run_javascript:
+ * // return exit('escalation', { reason: 'Technical issue', details: '...' })
  *
  * // Type-safe result handling
  * if (result.is(escalation)) {
@@ -129,7 +131,7 @@ export declare namespace Exit {
  *
  * ### Exit Aliases
  *
- * Multiple names for the same exit:
+ * Alternative names for the same exit:
  *
  * ```typescript
  * const exit = new Exit({
@@ -138,7 +140,8 @@ export declare namespace Exit {
  *   description: 'Task completed successfully',
  * })
  *
- * // Agent can use any alias: return { action: 'done' } or { action: 'finished' }
+ * // JavaScript can return exit('complete'), exit('done'), or another registered alias.
+ * // These all select the same exit without creating additional native tools.
  * ```
  *
  * ### Exit Metadata for Orchestration
@@ -216,26 +219,26 @@ export declare namespace Exit {
  * @template T - The type of data this exit returns (inferred from schema)
  *
  * @see {@link ExecutionResult} For result handling
- * @see {@link ThinkExit} Built-in thinking exit
  * @see {@link ListenExit} Built-in chat listening exit
  * @see {@link DefaultExit} Built-in completion exit
  */
 export declare class Exit<T = unknown> implements Serializable<Exit.JSON> {
-    /** The primary name of the exit (used in return statements) */
+    /** The primary name of the exit (used by its native exit tool) */
     name: string;
-    /** Alternative names that can be used to reference this exit */
+    /** Host-side aliases; the native tool uses only the primary name */
     aliases: string[];
     /** Human-readable description of when this exit should be used */
     description: string;
     /** Additional metadata for orchestration and custom logic */
     metadata: Record<string, unknown>;
-    /** JSON Schema for validating exit result data */
+    /** Model-facing payload description. The original validator is retained in zSchema. */
     schema?: JSONSchema7;
+    private _schema?;
     /**
-     * Returns the Zod schema equivalent of the JSON schema (if available).
+     * Returns the original runtime validator, preserving transforms and refinements.
      * Used internally for validation and type inference.
      */
-    get zSchema(): import("@bpinternal/zui").ZodType<any, import("@bpinternal/zui").ZodTypeDef, any> | undefined;
+    get zSchema(): z.ZodType<T, any, unknown> | undefined;
     /**
      * Renames the exit and updates aliases accordingly.
      *
@@ -270,7 +273,7 @@ export declare class Exit<T = unknown> implements Serializable<Exit.JSON> {
      * // customExit is independent of originalExit
      * ```
      */
-    clone(): Exit<any>;
+    clone(): Exit<T>;
     /**
      * Type guard to check if this exit matches another exit by name.
      *
@@ -288,7 +291,7 @@ export declare class Exit<T = unknown> implements Serializable<Exit.JSON> {
      */
     match(result: ExitResult): result is ExitResult<T>;
     /**
-     * Serializes this exit to a JSON-compatible object.
+     * Serializes the model-facing description. JavaScript validators cannot be serialized; use clone() to retain them.
      *
      * @returns JSON representation of the exit
      *
@@ -368,7 +371,7 @@ export declare class Exit<T = unknown> implements Serializable<Exit.JSON> {
         aliases?: string[];
         description: string;
         metadata?: Record<string, unknown>;
-        schema?: ZuiType<T>;
+        schema?: ZuiType<T, unknown>;
     });
     /**
      * Ensures all exits in an array have unique names by renaming duplicates.