llmz 0.0.13 → 0.0.14

package/dist/exit.d.ts

@@ -1,20 +1,334 @@
 import { JSONSchema7 } from 'json-schema';
 import { ZuiType } from './types.js';
+/**
+ * Represents the result of an agent execution that exited with a specific Exit.
+ *
+ * @template T - The type of the exit result data
+ */
 export type ExitResult<T = unknown> = {
+    /** The Exit instance that was used to terminate execution */
     exit: Exit<T>;
+    /** The result data returned by the exit (validated against the exit's schema) */
     result: T;
 };
+/**
+ * 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.
+ *
+ * ## Core Concepts
+ *
+ * **Termination Control**: Exits define the valid ways an agent execution can end.
+ * Unlike traditional functions that just return values, LLMz agents must explicitly
+ * exit through predefined exits, ensuring controlled and predictable termination.
+ *
+ * **Type Safety**: Each exit can define a Zod/Zui schema that validates the return data,
+ * providing compile-time and runtime type safety for execution results.
+ *
+ * **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)
+ * for common patterns, while custom exits enable domain-specific termination logic.
+ *
+ * ## Usage Patterns
+ *
+ * ### Simple Exit (No Data)
+ *
+ * For basic flow control without additional data:
+ *
+ * ```typescript
+ * const exit = new Exit({
+ *   name: 'exit',
+ *   description: 'When the user wants to exit the program',
+ * })
+ *
+ * // Agent usage: return { action: 'exit' }
+ *
+ * // Result handling
+ * if (result.is(exit)) {
+ *   console.log('User chose to exit')
+ *   process.exit(0)
+ * }
+ * ```
+ *
+ * ### Exit with Schema (Typed Data)
+ *
+ * For structured data extraction with validation:
+ *
+ * ```typescript
+ * const escalation = new Exit({
+ *   name: 'escalation',
+ *   description: 'Escalate the issue to a human agent',
+ *   schema: z.object({
+ *     reason: z.enum(['Frustrated user', 'Technical issue', 'Sensitive topic', 'Other']),
+ *     priority: z.enum(['low', 'medium', 'high']).default('medium'),
+ *     details: z.string(),
+ *   }),
+ * })
+ *
+ * // Agent usage: return { action: 'escalation', reason: 'Technical issue', details: '...' }
+ *
+ * // Type-safe result handling
+ * if (result.is(escalation)) {
+ *   console.log(`Escalation: ${result.output.reason}`)
+ *   console.log(`Priority: ${result.output.priority}`)
+ *   console.log(`Details: ${result.output.details}`)
+ * }
+ * ```
+ *
+ * ### Multiple Exits for Decision Making
+ *
+ * Enabling different execution paths:
+ *
+ * ```typescript
+ * const approved = new Exit({
+ *   name: 'approved',
+ *   description: 'Request was approved',
+ *   schema: z.object({
+ *     amount: z.number(),
+ *     reference: z.string(),
+ *   }),
+ * })
+ *
+ * const rejected = new Exit({
+ *   name: 'rejected',
+ *   description: 'Request was rejected',
+ *   schema: z.object({
+ *     reason: z.string(),
+ *   }),
+ * })
+ *
+ * const result = await execute({
+ *   instructions: 'Process the loan application',
+ *   exits: [approved, rejected],
+ *   tools: [reviewTool, creditCheckTool],
+ *   client,
+ * })
+ *
+ * if (result.is(approved)) {
+ *   console.log(`Approved: $${result.output.amount} (${result.output.reference})`)
+ * } else if (result.is(rejected)) {
+ *   console.log(`Rejected: ${result.output.reason}`)
+ * }
+ * ```
+ *
+ * ## Advanced Features
+ *
+ * ### Exit Aliases
+ *
+ * Multiple names for the same exit:
+ *
+ * ```typescript
+ * const exit = new Exit({
+ *   name: 'complete',
+ *   aliases: ['done', 'finished', 'end'],
+ *   description: 'Task completed successfully',
+ * })
+ *
+ * // Agent can use any alias: return { action: 'done' } or { action: 'finished' }
+ * ```
+ *
+ * ### Exit Metadata for Orchestration
+ *
+ * Additional data for complex systems:
+ *
+ * ```typescript
+ * const handoff = new Exit({
+ *   name: 'handoff_sales',
+ *   description: 'Handoff to sales agent',
+ *   metadata: {
+ *     type: 'handoff',
+ *     agent: 'sales',
+ *     department: 'customer_service',
+ *   },
+ *   schema: z.object({
+ *     reason: z.string(),
+ *     context: z.record(z.any()),
+ *   }),
+ * })
+ *
+ * // Use metadata in exit callbacks
+ * onExit: async (result) => {
+ *   if (result.exit.metadata?.type === 'handoff') {
+ *     await routeToAgent(result.exit.metadata.agent, result.result)
+ *   }
+ * }
+ * ```
+ *
+ * ### Exit Callbacks and Hooks
+ *
+ * Custom logic when exits are triggered:
+ *
+ * ```typescript
+ * const result = await execute({
+ *   instructions: 'Process customer request',
+ *   exits: [approved, rejected],
+ *   onExit: async (exitResult) => {
+ *     // Called before execution completes
+ *     await logOutcome(exitResult.exit.name, exitResult.result)
+ *
+ *     // Can throw to prevent exit and force retry
+ *     if (needsManagerApproval(exitResult)) {
+ *       throw new Error('Manager approval required')
+ *     }
+ *   },
+ *   client,
+ * })
+ * ```
+ *
+ * ## Exit Cloning and Modification
+ *
+ * Create variations of existing exits:
+ *
+ * ```typescript
+ * const baseExit = new Exit({
+ *   name: 'base',
+ *   description: 'Base exit',
+ *   schema: z.object({ status: z.string() }),
+ * })
+ *
+ * const customExit = baseExit.clone().rename('custom')
+ * // Creates independent copy with new name
+ * ```
+ *
+ * ## Best Practices
+ *
+ * 1. **Descriptive Names**: Use clear, action-oriented names that describe the outcome
+ * 2. **Comprehensive Schemas**: Define complete data structures with descriptions
+ * 3. **Multiple Exits**: Design multiple exits for different execution paths
+ * 4. **Type Safety**: Always use `result.is(exit)` for type-safe result handling
+ * 5. **Documentation**: Provide clear descriptions for both the exit and schema fields
+ * 6. **Validation**: Use Zod's validation features (enums, constraints, defaults)
+ *
+ * @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> {
+    /** The primary name of the exit (used in return statements) */
     name: string;
+    /** Alternative names that can be used to reference this exit */
     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 */
     schema?: JSONSchema7;
+    /**
+     * Returns the Zod schema equivalent of the JSON schema (if available).
+     * Used internally for validation and type inference.
+     */
     get zSchema(): import("@bpinternal/zui").ZodTypeAny | undefined;
+    /**
+     * Renames the exit and updates aliases accordingly.
+     *
+     * @param name - The new name for the exit (must be a valid identifier)
+     * @returns This exit instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const exit = new Exit({ name: 'old_name', description: 'Test exit' })
+     * exit.rename('new_name')
+     * console.log(exit.name) // 'new_name'
+     * ```
+     */
     rename(name: string): this;
+    /**
+     * Creates a deep copy of this exit.
+     *
+     * The clone is completely independent and can be modified without affecting
+     * the original exit. This is useful for creating variations of existing exits.
+     *
+     * @returns A new Exit instance with the same configuration
+     *
+     * @example
+     * ```typescript
+     * const originalExit = new Exit({
+     *   name: 'base',
+     *   description: 'Base exit',
+     *   schema: z.object({ status: z.string() }),
+     * })
+     *
+     * const customExit = originalExit.clone().rename('custom')
+     * // customExit is independent of originalExit
+     * ```
+     */
     clone(): Exit<any>;
+    /**
+     * Type guard to check if this exit matches another exit by name.
+     *
+     * Used internally for type narrowing and exit comparison.
+     *
+     * @param exit - The exit to compare against
+     * @returns True if the exits have the same name
+     */
     is<T>(exit: Exit<T>): this is Exit<T>;
+    /**
+     * Type guard to check if an ExitResult matches this exit.
+     *
+     * @param result - The exit result to check
+     * @returns True if the result was created by this exit
+     */
     match(result: ExitResult): result is ExitResult<T>;
+    /**
+     * Creates a new Exit instance.
+     *
+     * @param props - Exit configuration
+     * @param props.name - Primary name for the exit (must be valid identifier)
+     * @param props.description - Human-readable description of the exit's purpose
+     * @param props.aliases - Alternative names that can be used to reference this exit
+     * @param props.metadata - Additional data for orchestration and custom logic
+     * @param props.schema - Zod schema for validating exit result data
+     *
+     * @example
+     * ```typescript
+     * // Simple exit without data validation
+     * const exit = new Exit({
+     *   name: 'complete',
+     *   description: 'Task completed successfully',
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Exit with typed result data
+     * const approval = new Exit({
+     *   name: 'approved',
+     *   description: 'Request approved by system',
+     *   schema: z.object({
+     *     amount: z.number().positive(),
+     *     reference: z.string().min(1),
+     *     timestamp: z.date().default(() => new Date()),
+     *   }),
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Exit with aliases and metadata
+     * const handoff = new Exit({
+     *   name: 'handoff_support',
+     *   aliases: ['escalate', 'transfer'],
+     *   description: 'Transfer to human support agent',
+     *   metadata: {
+     *     department: 'customer_service',
+     *     priority: 'high',
+     *   },
+     *   schema: z.object({
+     *     reason: z.string(),
+     *     customerData: z.record(z.any()),
+     *   }),
+     * })
+     * ```
+     */
     constructor(props: {
         name: string;
         aliases?: string[];
@@ -22,5 +336,24 @@ export declare class Exit<T = unknown> {
         metadata?: Record<string, unknown>;
         schema?: ZuiType<T>;
     });
+    /**
+     * Ensures all exits in an array have unique names by renaming duplicates.
+     *
+     * When multiple exits have the same name, this method appends numbers to
+     * create unique names (e.g., 'exit1', 'exit2'). This prevents naming conflicts
+     * in execution contexts with multiple exits.
+     *
+     * @param exits - Array of exits that may have duplicate names
+     * @returns Array of exits with guaranteed unique names
+     *
+     * @example
+     * ```typescript
+     * const exit1 = new Exit({ name: 'done', description: 'First done' })
+     * const exit2 = new Exit({ name: 'done', description: 'Second done' })
+     *
+     * const uniqueExits = Exit.withUniqueNames([exit1, exit2])
+     * // Result: [{ name: 'done' }, { name: 'done1' }]
+     * ```
+     */
     static withUniqueNames: (exits: Exit[]) => Exit<unknown>[];
 }

package/dist/index.cjs

@@ -8,11 +8,11 @@
 
 
 
-var _chunkHJKOSEH2cjs = require('./chunk-HJKOSEH2.cjs');
+var _chunkGOJY4GRLcjs = require('./chunk-GOJY4GRL.cjs');
 require('./chunk-SHJDRZF5.cjs');
 
 
-var _chunkC6WNNTEVcjs = require('./chunk-C6WNNTEV.cjs');
+var _chunkKG7DT7WDcjs = require('./chunk-KG7DT7WD.cjs');
 
 
 
@@ -26,7 +26,7 @@ var _chunkJDABP4SDcjs = require('./chunk-JDABP4SD.cjs');
 require('./chunk-IKSIOIIP.cjs');
 
 
-var _chunkGWFYZDURcjs = require('./chunk-GWFYZDUR.cjs');
+var _chunkWL7ZIMYDcjs = require('./chunk-WL7ZIMYD.cjs');
 
 
 
@@ -307,6 +307,62 @@ var ObjectInstance = class {
   
   
   
+  /**
+   * Creates a new ObjectInstance.
+   *
+   * @param props - Object configuration
+   * @param props.name - Unique object name (must be valid TypeScript identifier)
+   * @param props.description - Human-readable description of the object
+   * @param props.tools - Array of tools to group under this object namespace
+   * @param props.properties - Array of stateful properties for this object
+   * @param props.metadata - Additional metadata for the object
+   *
+   * @throws Error if name is not a valid identifier
+   * @throws Error if description is not a string
+   * @throws Error if metadata is not an object
+   * @throws Error if properties/tools are not arrays
+   * @throws Error if properties exceed 100 limit
+   * @throws Error if property names are duplicated or invalid
+   * @throws Error if property descriptions exceed 5000 characters
+   *
+   * @example
+   * ```typescript
+   * const userProfile = new ObjectInstance({
+   *   name: 'user',
+   *   description: 'User profile management',
+   *   properties: [
+   *     {
+   *       name: 'name',
+   *       value: 'John Doe',
+   *       type: z.string().min(1),
+   *       description: 'User full name',
+   *       writable: true,
+   *     },
+   *     {
+   *       name: 'email',
+   *       value: null,
+   *       type: z.string().email().nullable(),
+   *       description: 'User email address',
+   *       writable: true,
+   *     },
+   *   ],
+   *   tools: [
+   *     new Tool({
+   *       name: 'updateProfile',
+   *       input: z.object({ name: z.string(), email: z.string() }),
+   *       handler: async ({ name, email }) => {
+   *         // Update external system
+   *         await updateUserInDatabase({ name, email })
+   *       },
+   *     }),
+   *   ],
+   *   metadata: {
+   *     version: '1.0',
+   *     category: 'user-management',
+   *   },
+   * })
+   * ```
+   */
   constructor(props) {
     var _a;
     if (!_chunk276Q6EWPcjs.isValidIdentifier.call(void 0, props.name)) {
@@ -366,8 +422,45 @@ var ObjectInstance = class {
     this.description = props.description;
     this.metadata = _nullishCoalesce(props.metadata, () => ( {}));
     this.properties = props.properties;
-    this.tools = _chunkC6WNNTEVcjs.Tool.withUniqueNames(_nullishCoalesce(props.tools, () => ( [])));
+    this.tools = _chunkKG7DT7WDcjs.Tool.withUniqueNames(_nullishCoalesce(props.tools, () => ( [])));
   }
+  /**
+   * Generates TypeScript namespace declarations for this object.
+   *
+   * This method creates TypeScript definitions that are included in the LLM context
+   * to help it understand the available properties and tools. Properties become
+   * const declarations with appropriate Readonly/Writable types, and tools become
+   * function signatures.
+   *
+   * @returns Promise resolving to TypeScript namespace declaration
+   *
+   * @example
+   * ```typescript
+   * const obj = new ObjectInstance({
+   *   name: 'user',
+   *   properties: [
+   *     { name: 'name', value: 'John', writable: true },
+   *     { name: 'id', value: 123, writable: false },
+   *   ],
+   *   tools: [
+   *     new Tool({
+   *       name: 'save',
+   *       input: z.object({ data: z.string() }),
+   *       handler: async ({ data }) => { /* ... *\/ },
+   *     }),
+   *   ],
+   * })
+   *
+   * const typings = await obj.getTypings()
+   * console.log(typings)
+   * // Output:
+   * // export namespace user {
+   * //   const name: Writable<string> = "John"
+   * //   const id: Readonly<number> = 123
+   * //   function save(args: { data: string }): Promise<void>
+   * // }
+   * ```
+   */
   async getTypings() {
     return getObjectTypings(this).withProperties().withTools().build();
   }
@@ -866,25 +959,129 @@ var Chat = class {
   
   
   
+  /**
+   * Creates a new Chat instance.
+   *
+   * @param props - Chat configuration
+   * @param props.handler - Function to handle agent messages (called for every agent output)
+   * @param props.components - Available UI components (static array or dynamic function)
+   * @param props.transcript - Conversation history (static array or dynamic function, defaults to empty)
+   *
+   * @example
+   * ```typescript
+   * // Basic chat with static configuration
+   * const chat = new Chat({
+   *   handler: async (input) => {
+   *     if (isComponent(input, DefaultComponents.Text)) {
+   *       console.log('Agent:', input.children.join(''))
+   *     }
+   *   },
+   *   components: [DefaultComponents.Text, DefaultComponents.Button],
+   *   transcript: [
+   *     { role: 'user', content: 'Hello', timestamp: Date.now() }
+   *   ],
+   * })
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Dynamic chat with functions for real-time updates
+   * class MyChat extends Chat {
+   *   private messages: Transcript.Message[] = []
+   *
+   *   constructor() {
+   *     super({
+   *       handler: (input) => this.handleMessage(input),
+   *
+   *       // Dynamic components - can change during execution
+   *       components: () => [
+   *         DefaultComponents.Text,
+   *         DefaultComponents.Button,
+   *         ...this.getCustomComponents()
+   *       ],
+   *
+   *       // Dynamic transcript - always reflects current state
+   *       transcript: () => this.messages,
+   *     })
+   *   }
+   * }
+   * ```
+   */
   constructor(props) {
     this.handler = props.handler;
     this.components = props.components;
     this.transcript = props.transcript || [];
   }
+  /**
+   * Called when an execution cycle completes, regardless of the outcome.
+   *
+   * Override this method to handle execution results, manage conversation flow,
+   * or perform cleanup tasks. This is called after each `execute()` call completes,
+   * whether it succeeds, fails, or is interrupted.
+   *
+   * @param result - The execution result containing status, iterations, and exit information
+   *
+   * @example
+   * ```typescript
+   * class MyChat extends Chat {
+   *   public result?: ExecutionResult
+   *
+   *   onExecutionDone(result: ExecutionResult) {
+   *     // Store result for conversation flow control
+   *     this.result = result
+   *
+   *     // Handle different result types
+   *     if (result.isSuccess()) {
+   *       console.log('✅ Execution completed successfully')
+   *       console.log('Exit:', result.output.exit_name)
+   *     } else if (result.isError()) {
+   *       console.error('❌ Execution failed:', result.output.error)
+   *     } else if (result.isInterrupted()) {
+   *       console.log('⏸️ Execution interrupted (partial result)')
+   *     }
+   *   }
+   *
+   *   // Use stored result for conversation flow
+   *   isWaitingForInput(): boolean {
+   *     return this.result?.is(ListenExit) ?? false
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // CLIChat implementation example
+   * class CLIChat extends Chat {
+   *   public status?: IterationStatus
+   *   public result?: ExecutionResult
+   *
+   *   onExecutionDone(result: ExecutionResult) {
+   *     this.result = result
+   *     this.status = result.iterations.at(-1)?.status
+   *   }
+   *
+   *   // Check if agent exited with specific exit type
+   *   hasExitedWith<R>(exit: Exit<R>): boolean {
+   *     return this.status?.type === 'exit_success' &&
+   *            this.status.exit_success.exit_name === exit.name
+   *   }
+   * }
+   * ```
+   */
   onExecutionDone(_result) {
   }
 };
 
 // src/index.ts
 var execute = async (props) => {
-  const { executeContext } = await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-QLZBDG2Z.cjs")));
+  const { executeContext } = await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-TR4CQK4F.cjs")));
   return executeContext(props);
 };
 var init = async () => {
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-QLZBDG2Z.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./llmz-TR4CQK4F.cjs")));
   await Promise.resolve().then(() => _interopRequireWildcard(require("./component-R4WTW6DZ.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./tool-QP4MVRWI.cjs")));
-  await Promise.resolve().then(() => _interopRequireWildcard(require("./exit-TRXEU4OU.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./tool-NS7EGK7Z.cjs")));
+  await Promise.resolve().then(() => _interopRequireWildcard(require("./exit-O2WZUEFS.cjs")));
   await Promise.resolve().then(() => _interopRequireWildcard(require("./jsx-AJAXBWFE.cjs")));
   await Promise.resolve().then(() => _interopRequireWildcard(require("./vm-2DLG7V4G.cjs")));
   await Promise.resolve().then(() => _interopRequireWildcard(require("./utils-A7WNEFTA.cjs")));
@@ -918,4 +1115,4 @@ var init = async () => {
 
 
 
-exports.Chat = Chat; exports.CitationsManager = CitationsManager; exports.Component = _chunkZRCU35UVcjs.Component; exports.DefaultComponents = DefaultComponents; exports.DefaultExit = _chunkHJKOSEH2cjs.DefaultExit; exports.ErrorExecutionResult = _chunkHJKOSEH2cjs.ErrorExecutionResult; exports.ExecutionResult = _chunkHJKOSEH2cjs.ExecutionResult; exports.Exit = _chunkGWFYZDURcjs.Exit; exports.ListenExit = _chunkHJKOSEH2cjs.ListenExit; exports.LoopExceededError = _chunkJDABP4SDcjs.LoopExceededError; exports.ObjectInstance = ObjectInstance; exports.PartialExecutionResult = _chunkHJKOSEH2cjs.PartialExecutionResult; exports.Snapshot = _chunkHJKOSEH2cjs.Snapshot; exports.SnapshotSignal = _chunkJDABP4SDcjs.SnapshotSignal; exports.SuccessExecutionResult = _chunkHJKOSEH2cjs.SuccessExecutionResult; exports.ThinkExit = _chunkHJKOSEH2cjs.ThinkExit; exports.ThinkSignal = _chunkJDABP4SDcjs.ThinkSignal; exports.Tool = _chunkC6WNNTEVcjs.Tool; exports.assertValidComponent = _chunkZRCU35UVcjs.assertValidComponent; exports.execute = execute; exports.getValue = _chunkHJKOSEH2cjs.getValue; exports.init = init; exports.isAnyComponent = _chunkZRCU35UVcjs.isAnyComponent; exports.isComponent = _chunkZRCU35UVcjs.isComponent; exports.renderToTsx = _chunkZRCU35UVcjs.renderToTsx;
+exports.Chat = Chat; exports.CitationsManager = CitationsManager; exports.Component = _chunkZRCU35UVcjs.Component; exports.DefaultComponents = DefaultComponents; exports.DefaultExit = _chunkGOJY4GRLcjs.DefaultExit; exports.ErrorExecutionResult = _chunkGOJY4GRLcjs.ErrorExecutionResult; exports.ExecutionResult = _chunkGOJY4GRLcjs.ExecutionResult; exports.Exit = _chunkWL7ZIMYDcjs.Exit; exports.ListenExit = _chunkGOJY4GRLcjs.ListenExit; exports.LoopExceededError = _chunkJDABP4SDcjs.LoopExceededError; exports.ObjectInstance = ObjectInstance; exports.PartialExecutionResult = _chunkGOJY4GRLcjs.PartialExecutionResult; exports.Snapshot = _chunkGOJY4GRLcjs.Snapshot; exports.SnapshotSignal = _chunkJDABP4SDcjs.SnapshotSignal; exports.SuccessExecutionResult = _chunkGOJY4GRLcjs.SuccessExecutionResult; exports.ThinkExit = _chunkGOJY4GRLcjs.ThinkExit; exports.ThinkSignal = _chunkJDABP4SDcjs.ThinkSignal; exports.Tool = _chunkKG7DT7WDcjs.Tool; exports.assertValidComponent = _chunkZRCU35UVcjs.assertValidComponent; exports.execute = execute; exports.getValue = _chunkGOJY4GRLcjs.getValue; exports.init = init; exports.isAnyComponent = _chunkZRCU35UVcjs.isAnyComponent; exports.isComponent = _chunkZRCU35UVcjs.isComponent; exports.renderToTsx = _chunkZRCU35UVcjs.renderToTsx;

package/dist/index.d.ts

@@ -14,6 +14,68 @@ export { ErrorExecutionResult, ExecutionResult, PartialExecutionResult, SuccessE
 export { Trace } from './types.js';
 export { type Iteration, ListenExit, ThinkExit, DefaultExit, IterationStatuses, IterationStatus } from './context.js';
 export { type ValueOrGetter, getValue } from './getter.js';
+/**
+ * Executes an LLMz agent in either Chat Mode or Worker Mode.
+ *
+ * LLMz is a code-first AI agent framework that generates and runs TypeScript code
+ * in a sandbox rather than using traditional JSON tool calling. This enables complex
+ * logic, multi-tool orchestration, and native LLM thinking via comments and code structure.
+ *
+ * @param props - Configuration object for the execution
+ * @param props.client - Botpress Client or Cognitive Client instance for LLM generation
+ * @param props.instructions - System prompt/instructions for the LLM (static string or dynamic function)
+ * @param props.chat - Optional Chat instance to enable Chat Mode with user interaction
+ * @param props.tools - Array of Tool instances available to the agent (static or dynamic)
+ * @param props.objects - Array of ObjectInstance for namespaced tools and variables (static or dynamic)
+ * @param props.exits - Array of Exit definitions for structured completion (static or dynamic)
+ * @param props.snapshot - Optional Snapshot to resume paused execution
+ * @param props.signal - Optional AbortSignal to cancel execution
+ * @param props.options - Optional execution options (loop limit, temperature, model, timeout)
+ * @param props.onTrace - Optional non-blocking hook for monitoring traces during execution
+ * @param props.onIterationEnd - Optional blocking hook called after each iteration
+ * @param props.onExit - Optional blocking hook called when an exit is reached (can prevent exit)
+ * @param props.onBeforeExecution - Optional blocking hook to modify code before VM execution
+ * @param props.onBeforeTool - Optional blocking hook to modify tool inputs before execution
+ * @param props.onAfterTool - Optional blocking hook to modify tool outputs after execution
+ *
+ * @returns Promise<ExecutionResult> - Result containing success/error/interrupted status with type-safe exit checking
+ *
+ * @example
+ * // Worker Mode - Automated execution
+ * const result = await execute({
+ *   client: cognitiveClient,
+ *   instructions: 'Calculate the sum of numbers 1 to 100',
+ *   exits: [myExit]
+ * })
+ *
+ * if (result.is(myExit)) {
+ *   console.log('Result:', result.output)
+ * }
+ *
+ * @example
+ * // Chat Mode - Interactive conversation
+ * const result = await execute({
+ *   client: cognitiveClient,
+ *   instructions: 'You are a helpful assistant',
+ *   chat: myChatInstance,
+ *   tools: [searchTool, calculatorTool]
+ * })
+ *
+ * if (result.is(ListenExit)) {
+ *   // Agent is waiting for user input
+ * }
+ *
+ * @example
+ * // With dynamic instructions and hooks
+ * const result = await execute({
+ *   client: cognitiveClient,
+ *   instructions: (ctx) => `Process ${ctx.variables.dataCount} records`,
+ *   tools: async (ctx) => await getContextualTools(ctx),
+ *   options: { loop: 10, temperature: 0.1 },
+ *   onTrace: ({ trace, iteration }) => console.log(trace),
+ *   onExit: async (result) => await validateResult(result)
+ * })
+ */
 export declare const execute: (props: ExecutionProps) => Promise<ExecutionResult>;
 /**
  * Loads the necessary dependencies for the library to work