llmz 0.0.13 → 0.0.15

package/dist/chat.d.ts

@@ -3,15 +3,340 @@ import { Context } from './context.js';
 import { ValueOrGetter } from './getter.js';
 import { ExecutionResult } from './result.js';
 import { TranscriptArray, Transcript } from './transcript.js';
+/**
+ * Function type for handling messages sent from the agent to the user.
+ *
+ * The handler receives rendered components from the agent and is responsible for
+ * presenting them to the user through the appropriate interface (CLI, web UI, mobile app, etc.).
+ * This is how the agent communicates with the user.
+ *
+ * @param input - The rendered component to display to the user
+ * @returns Promise that resolves when the message has been handled
+ *
+ * @example
+ * ```typescript
+ * const handler: MessageHandler = async (input) => {
+ *   if (isComponent(input, DefaultComponents.Text)) {
+ *     console.log('Agent:', input.children.join(''))
+ *   } else if (isComponent(input, DefaultComponents.Button)) {
+ *     console.log('Button:', input.props.label)
+ *   }
+ * }
+ * ```
+ */
 export type MessageHandler = (input: RenderedComponent) => Promise<void> | void;
+/**
+ * Base class for implementing chat interfaces in LLMz agents.
+ *
+ * The Chat class provides the foundation for interactive conversational agents by defining
+ * how agents communicate with users. It manages the conversation transcript, available UI
+ * components, and message handling. This is the bridge between the agent's generated code
+ * and your user interface.
+ *
+ * ## Key Concepts
+ *
+ * **Handler Function**: The core method that receives agent messages (rendered components)
+ * and displays them to the user. This is called every time the agent wants to communicate.
+ *
+ * **Transcript**: An up-to-date conversation history that is evaluated at each iteration.
+ * The transcript must reflect the complete conversation state as the agent uses it to
+ * understand context and generate appropriate responses.
+ *
+ * **Components**: The UI elements available to the agent for creating rich interactive
+ * experiences (text, buttons, images, cards, etc.).
+ *
+ * ## Implementation Requirements
+ *
+ * To create a functional chat interface, you must:
+ * 1. Implement the MessageHandler to display agent messages to users
+ * 2. Maintain an accurate transcript of the conversation
+ * 3. Provide the available UI components (typically includes DefaultComponents)
+ * 4. Optional: Override onExecutionDone() to handle execution completion
+ *
+ * ## Basic Implementation
+ *
+ * ```typescript
+ * import { Chat, DefaultComponents, isComponent } from 'llmz'
+ *
+ * class MyChat extends Chat {
+ *   private messages: Array<{role: 'user' | 'assistant', content: string}> = []
+ *
+ *   constructor() {
+ *     super({
+ *       // Handle agent messages - this is called for every agent output
+ *       handler: async (input) => {
+ *         if (isComponent(input, DefaultComponents.Text)) {
+ *           const text = input.children.join('')
+ *           console.log('Agent:', text)
+ *           this.messages.push({ role: 'assistant', content: text })
+ *         } else if (isComponent(input, DefaultComponents.Button)) {
+ *           console.log('Button:', input.props.label)
+ *         }
+ *       },
+ *
+ *       // Provide available components - agent can use these in generated code
+ *       components: [DefaultComponents.Text, DefaultComponents.Button],
+ *
+ *       // Return current transcript - evaluated at each iteration
+ *       transcript: () => this.messages,
+ *     })
+ *   }
+ *
+ *   // Add user message to transcript
+ *   addUserMessage(content: string) {
+ *     this.messages.push({ role: 'user', content })
+ *   }
+ * }
+ *
+ * // Usage
+ * const chat = new MyChat()
+ * chat.addUserMessage('Hello!')
+ *
+ * const result = await execute({
+ *   instructions: 'You are a helpful assistant',
+ *   chat, // Enable chat mode
+ *   client,
+ * })
+ * ```
+ *
+ * ## Advanced Implementation (CLIChat Example)
+ *
+ * ```typescript
+ * import { Chat, DefaultComponents, ListenExit } from 'llmz'
+ *
+ * class CLIChat extends Chat {
+ *   public transcript: Array<{role: 'user' | 'assistant', content: string}> = []
+ *   private buttons: string[] = []
+ *   public result?: ExecutionResult
+ *
+ *   constructor() {
+ *     super({
+ *       // Dynamic component list with custom renderers
+ *       components: () => [
+ *         DefaultComponents.Text,
+ *         DefaultComponents.Button,
+ *         ...this.customComponents
+ *       ],
+ *
+ *       // Dynamic transcript access
+ *       transcript: () => this.transcript,
+ *
+ *       // Sophisticated message handling
+ *       handler: async (input) => {
+ *         if (isComponent(input, DefaultComponents.Text)) {
+ *           const text = input.children.join('')
+ *           console.log('🤖 Agent:', text)
+ *           this.transcript.push({ role: 'assistant', content: text })
+ *         } else if (isComponent(input, DefaultComponents.Button)) {
+ *           this.buttons.push(input.props.label)
+ *         }
+ *       },
+ *     })
+ *   }
+ *
+ *   // Handle execution completion
+ *   onExecutionDone(result: ExecutionResult) {
+ *     this.result = result
+ *   }
+ *
+ *   // Check if agent is waiting for user input
+ *   isWaitingForInput(): boolean {
+ *     return this.result?.is(ListenExit) ?? false
+ *   }
+ *
+ *   // Conversation loop
+ *   async iterate(): Promise<boolean> {
+ *     if (this.isWaitingForInput()) {
+ *       const userInput = await this.promptUser()
+ *       this.transcript.push({ role: 'user', content: userInput })
+ *       return true // Continue conversation
+ *     }
+ *     return false // End conversation
+ *   }
+ * }
+ * ```
+ *
+ * ## Component System
+ *
+ * The agent generates JSX code using available components:
+ *
+ * ```typescript
+ * // Agent generates this TSX code:
+ * yield <Text>Welcome! Choose an option:</Text>
+ * yield <Button action="postback" label="Get Help" value="help" />
+ * yield <Button action="postback" label="Contact Sales" value="sales" />
+ *
+ * // Your handler receives these as RenderedComponent objects
+ * ```
+ *
+ * ## Transcript Management
+ *
+ * The transcript is critical for agent context and must be kept up-to-date:
+ *
+ * ```typescript
+ * // ❌ Bad - static transcript
+ * transcript: [{ role: 'user', content: 'Hello' }]
+ *
+ * // ✅ Good - dynamic transcript that reflects current state
+ * transcript: () => this.messages
+ *
+ * // The transcript is evaluated at each iteration, so the agent
+ * // always sees the current conversation state
+ * ```
+ *
+ * ## Custom Components
+ *
+ * Extend the UI with custom components for your specific use case:
+ *
+ * ```typescript
+ * import { Component } from 'llmz'
+ *
+ * const ProductCard = new Component({
+ *   type: 'leaf',
+ *   name: 'ProductCard',
+ *   leaf: {
+ *     props: z.object({
+ *       name: z.string(),
+ *       price: z.number(),
+ *       imageUrl: z.string(),
+ *     })
+ *   }
+ * })
+ *
+ * class ShoppingChat extends Chat {
+ *   constructor() {
+ *     super({
+ *       components: [
+ *         ...DefaultComponents,
+ *         ProductCard, // Add custom component
+ *       ],
+ *       handler: async (input) => {
+ *         if (isComponent(input, ProductCard)) {
+ *           // Handle custom component rendering
+ *           this.renderProduct(input.props)
+ *         }
+ *         // ... handle other components
+ *       },
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DefaultComponents} For standard UI components
+ * @see {@link https://github.com/botpress/botpress/blob/master/packages/llmz/examples/utils/cli-chat.ts} Complete CLIChat implementation
+ */
 export declare class Chat {
     readonly handler: MessageHandler;
     readonly transcript: ValueOrGetter<TranscriptArray, Context>;
     readonly components: ValueOrGetter<Component[], Context>;
+    /**
+     * 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: {
         handler: MessageHandler;
         components: ValueOrGetter<Component[], Context>;
         transcript?: ValueOrGetter<Transcript.Message[], Context>;
     });
+    /**
+     * 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: ExecutionResult): void;
 }

package/dist/{chunk-KH6JQYQA.js → chunk-2D2DE7CD.js}

@@ -6,11 +6,11 @@ import {
 } from "./chunk-GGWM6X2K.js";
 import {
   wrapContent
-} from "./chunk-SNDVQU5A.js";
+} from "./chunk-3JYCCI4S.js";
 import {
   escapeString,
   getTokenizer
-} from "./chunk-4MNIJGK6.js";
+} from "./chunk-ZORRILUV.js";
 import {
   chain_default,
   countBy_default,

package/dist/chunk-3G3BS5IA.cjs

@@ -0,0 +1,256 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } var _class;
+
+
+
+var _chunkWHNOR4ZUcjs = require('./chunk-WHNOR4ZU.cjs');
+
+
+var _chunkUQOBUJIQcjs = require('./chunk-UQOBUJIQ.cjs');
+
+// src/exit.ts
+var _zui = require('@bpinternal/zui');
+var Exit = (_class = class _Exit {
+  /** The primary name of the exit (used in return statements) */
+  
+  /** Alternative names that can be used to reference this exit */
+  __init() {this.aliases = []}
+  /** Human-readable description of when this exit should be used */
+  
+  /** Additional metadata for orchestration and custom logic */
+  
+  /** JSON Schema for validating exit result data */
+  
+  /**
+   * Returns the Zod schema equivalent of the JSON schema (if available).
+   * Used internally for validation and type inference.
+   */
+  get zSchema() {
+    return this.schema ? _zui.transforms.fromJSONSchemaLegacy(this.schema) : void 0;
+  }
+  /**
+   * 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) {
+    const before = this.name;
+    if (!_chunkWHNOR4ZUcjs.isValidIdentifier.call(void 0, 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.`
+      );
+    }
+    this.name = name;
+    this.aliases = _chunkUQOBUJIQcjs.uniq_default.call(void 0, [name, ...this.aliases.map((alias) => alias === before ? name : alias)]);
+    return 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() {
+    return new _Exit({
+      name: this.name,
+      aliases: [...this.aliases],
+      description: this.description,
+      metadata: JSON.parse(JSON.stringify(this.metadata)),
+      schema: this.zSchema
+    });
+  }
+  /**
+   * 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(exit) {
+    return this.name === exit.name;
+  }
+  /**
+   * 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) {
+    return result.exit instanceof _Exit && this.name === result.exit.name;
+  }
+  /**
+   * Serializes this exit to a JSON-compatible object.
+   *
+   * @returns JSON representation of the exit
+   *
+   * @example
+   * ```typescript
+   * const exit = new Exit({
+   *   name: 'complete',
+   *   description: 'Task completed successfully',
+   * })
+   *
+   * console.log(exit.toJSON())
+   * // { name: 'complete', aliases: [], description: 'Task completed successfully', metadata: {}, schema: undefined }
+   * ```
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      aliases: [...this.aliases],
+      description: this.description,
+      metadata: { ...this.metadata },
+      schema: this.schema
+    };
+  }
+  /**
+   * 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) {;_class.prototype.__init.call(this);
+    if (!_chunkWHNOR4ZUcjs.isValidIdentifier.call(void 0, 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) => !_chunkWHNOR4ZUcjs.isValidIdentifier.call(void 0, alias))) {
+      throw new Error(`Invalid aliases for exit ${props.name}. Expected an array of valid identifiers.`);
+    }
+    if (typeof props.schema !== "undefined") {
+      if (_chunkWHNOR4ZUcjs.isZuiSchema.call(void 0, props.schema)) {
+        this.schema = _zui.transforms.toJSONSchemaLegacy(props.schema);
+      } else if (_chunkWHNOR4ZUcjs.isJsonSchema.call(void 0, 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}"`
+        );
+      }
+    }
+    this.name = props.name;
+    this.aliases = _chunkUQOBUJIQcjs.uniq_default.call(void 0, [props.name, ..._nullishCoalesce(props.aliases, () => ( []))]);
+    this.description = props.description;
+    this.metadata = _nullishCoalesce(props.metadata, () => ( {}));
+  }
+  /**
+   * 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 __initStatic() {this.withUniqueNames = (exits) => {
+    const names = /* @__PURE__ */ new Set();
+    return exits.map((exit) => {
+      if (exits.filter((t) => t.name === exit.name).length === 1) {
+        return exit;
+      }
+      let counter = 1;
+      let exitName = exit.name + counter;
+      while (names.has(exitName)) {
+        exitName = `${exit.name}${++counter}`;
+      }
+      return exit.rename(exitName);
+    });
+  }}
+}, _class.__initStatic(), _class);
+
+
+
+exports.Exit = Exit;

package/dist/{chunk-SNDVQU5A.js → chunk-3JYCCI4S.js}

@@ -1,6 +1,6 @@
 import {
   getTokenizer
-} from "./chunk-4MNIJGK6.js";
+} from "./chunk-ZORRILUV.js";
 
 // src/truncator.ts
 var DEFAULT_REMOVE_CHUNK = 250;