llmz 0.0.12 → 0.0.14

package/dist/chunk-XAN7HQP5.js

@@ -0,0 +1,231 @@
+import {
+  isJsonSchema,
+  isValidIdentifier,
+  isZuiSchema
+} from "./chunk-4MNIJGK6.js";
+import {
+  uniq_default
+} from "./chunk-7WRN4E42.js";
+
+// src/exit.ts
+import { transforms } from "@bpinternal/zui";
+var Exit = class _Exit {
+  /** The primary name of the exit (used in return statements) */
+  name;
+  /** Alternative names that can be used to reference this exit */
+  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 */
+  schema;
+  /**
+   * Returns the Zod schema equivalent of the JSON schema (if available).
+   * Used internally for validation and type inference.
+   */
+  get zSchema() {
+    return this.schema ? 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 (!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.`
+      );
+    }
+    this.name = name;
+    this.aliases = uniq_default([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;
+  }
+  /**
+   * 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) {
+    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 (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}"`
+        );
+      }
+    }
+    this.name = props.name;
+    this.aliases = uniq_default([props.name, ...props.aliases ?? []]);
+    this.description = props.description;
+    this.metadata = 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 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);
+    });
+  };
+};
+
+export {
+  Exit
+};

package/dist/context.d.ts

@@ -79,8 +79,220 @@ export declare namespace IterationStatuses {
         };
     };
 }
+/**
+ * Built-in exit for requesting thinking time during agent execution.
+ *
+ * The ThinkExit allows agents to pause execution and reflect on the current situation,
+ * variables, and context before continuing. There are two ways to trigger thinking:
+ *
+ * 1. **Agent-initiated**: Agent calls `return { action: 'think' }` to pause and reflect
+ * 2. **Tool/Hook-initiated**: Tools or hooks throw `ThinkSignal` to force agent reflection
+ *
+ * This exit is automatically available in all LLMz executions and is commonly used for:
+ * - Complex decision making that requires analysis
+ * - Debugging and understanding current variable state
+ * - Planning multi-step operations
+ * - Tool feedback and result processing
+ * - Reflecting on previous iterations and results
+ *
+ * @example
+ * ```typescript
+ * // Agent retrieves web search results and decides to think about them
+ * const results = await searchWeb(query)
+ *
+ * // Agent decides it needs to think (look at the search results) before responding
+ * return { action: 'think', results }
+ * ```
+ *
+ * Sometimes, as the author of the tool, you may want to always force the agent to think about the results.
+ * In this case, you can throw a `ThinkSignal` from the tool handler to trigger thinking.
+ *
+ * @example
+ * ```typescript
+ * // Tool-initiated thinking using ThinkSignal
+ * import { ThinkSignal } from 'llmz'
+ *
+ * const searchTool = new Tool({
+ *   name: 'search',
+ *   handler: async ({ query }) => {
+ *     const results = await performSearch(query)
+ *
+ *     if (!results.length) {
+ *       // Force agent to think about alternative approaches
+ *       throw new ThinkSignal(
+ *         'No search results found',
+ *         'No results were found. Consider rephrasing the query or using a different approach.'
+ *       )
+ *     }
+ *
+ *     // Provide context for agent to process results
+ *     throw new ThinkSignal(
+ *       'Search completed with results',
+ *       `Found ${results.length} results. Process them carefully and provide citations.`
+ *     )
+ *   }
+ * })
+ * ```
+ * When an iteration ends with ThinkExit, the agent will automatically loop and start a new iteration to continue processing, unless iteration limit is reached.
+ *
+ * The thinking process helps agents:
+ * - Avoid rushing into incorrect solutions
+ * - Better understand complex problems and tool results
+ * - Maintain variable state across iterations
+ * - Process feedback from tools and hooks
+ * - Provide more thoughtful and accurate responses
+ */
 export declare const ThinkExit: Exit<unknown>;
+/**
+ * Built-in exit for waiting for user input in chat mode.
+ *
+ * The ListenExit is automatically available when chat mode is enabled (when a Chat
+ * instance is provided to execute()). When an agent calls `return { action: 'listen' }`,
+ * the execution pauses and waits for user input before continuing the conversation.
+ *
+ * This exit is essential for interactive conversational agents and is used to:
+ * - Wait for user responses in chat interfaces
+ * - Pause execution until user provides input
+ * - Enable back-and-forth conversation flow
+ * - Allow users to guide the conversation direction
+ *
+ * The ListenExit is only available in chat mode - it will not be present in
+ * worker mode executions where no chat interface is provided.
+ *
+ * @example
+ * ```typescript
+ * // Agent generated code using ListenExit in chat mode
+ * yield <Message>What would you like me to help you with today?</Message>
+ * yield <Button action="postback" label="Get Weather" value="weather" />
+ * yield <Button action="postback" label="Set Reminder" value="reminder" />
+ *
+ * // Wait for user to respond
+ * return { action: 'listen' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Standard chat interaction pattern
+ * const calculation = 2 + 8
+ * yield <Message>The result of `2 + 8` is **{calculation}**.</Message>
+ * return { action: 'listen' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // CLI chat example with ListenExit handling
+ * const chat = new CLIChat()
+ *
+ * while (chat.iterate()) {
+ *   const result = await execute({
+ *     instructions: 'Help the user with their questions',
+ *     chat,
+ *     client,
+ *   })
+ *
+ *   if (result.is(ListenExit)) {
+ *     // CLIChat handles prompting user automatically
+ *     continue
+ *   } else {
+ *     console.log('Conversation ended')
+ *     break
+ *   }
+ * }
+ * ```
+ *
+ * The ListenExit enables natural conversation flow where:
+ * - Agent sends messages and waits for responses
+ * - User provides input to guide the conversation
+ * - Conversation continues iteratively until completion
+ * - Chat interface manages the input/output cycle
+ */
 export declare const ListenExit: Exit<unknown>;
+/**
+ * Default exit used when no custom exits are provided.
+ *
+ * The DefaultExit is automatically used in worker mode when no custom exits are defined.
+ * It provides a standard way to complete execution with either success or failure outcomes.
+ * The exit uses a discriminated union schema to ensure type-safe handling of both success
+ * and error cases.
+ *
+ * This exit is commonly used for:
+ * - Simple worker mode executions without custom completion logic
+ * - Standardized success/failure reporting
+ * - Basic task completion with result or error information
+ * - Default fallback when no specific exit behavior is needed
+ *
+ * @example
+ * ```typescript
+ * // Agent generated code using DefaultExit for successful completion
+ * const data = await fetchUserData(userId)
+ * const processedResult = processData(data)
+ *
+ * return {
+ *   action: 'done',
+ *   success: true,
+ *   result: processedResult
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Agent generated code using DefaultExit for error cases
+ * try {
+ *   const result = await riskyOperation()
+ *   return { action: 'done', success: true, result }
+ * } catch (error) {
+ *   return {
+ *     action: 'done',
+ *     success: false,
+ *     error: `Operation failed: ${error.message}`
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { execute, DefaultExit } from 'llmz'
+ *
+ * // Handling DefaultExit in execution results
+ * const result = await execute({
+ *   instructions: 'Process the user data and return results',
+ *   // No custom exits provided - DefaultExit will be used
+ *   client,
+ * })
+ *
+ * if (result.is(DefaultExit)) {
+ *   if (result.output.success) {
+ *     console.log('Success:', result.output.result)
+ *   } else {
+ *     console.error('Error:', result.output.error)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Worker mode execution with automatic DefaultExit
+ * const result = await execute({
+ *   instructions: 'Calculate fibonacci numbers up to 100',
+ *   tools: [mathTools],
+ *   client,
+ *   // No chat provided = worker mode
+ *   // No exits provided = DefaultExit automatically added
+ * })
+ *
+ * // Result will use DefaultExit for completion
+ * if (result.isSuccess() && result.is(DefaultExit)) {
+ *   const { success, result: data, error } = result.output
+ *   // Handle success/failure cases
+ * }
+ * ```
+ *
+ * The DefaultExit provides a consistent interface for:
+ * - Type-safe success/failure handling
+ * - Standardized result reporting across different executions
+ * - Automatic fallback behavior when no custom exits are defined
+ * - Clear separation between successful results and error conditions
+ */
 export declare const DefaultExit: Exit<{
     success: true;
     result?: any;

package/dist/{exit-YORW76T3.js → exit-7HDRH27N.js}

@@ -1,6 +1,6 @@
 import {
   Exit
-} from "./chunk-JMSZKB4T.js";
+} from "./chunk-XAN7HQP5.js";
 import "./chunk-4MNIJGK6.js";
 import "./chunk-7WRN4E42.js";
 export {

package/dist/{exit-TRXEU4OU.cjs → exit-O2WZUEFS.cjs}

@@ -1,8 +1,8 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkGWFYZDURcjs = require('./chunk-GWFYZDUR.cjs');
+var _chunkWL7ZIMYDcjs = require('./chunk-WL7ZIMYD.cjs');
 require('./chunk-276Q6EWP.cjs');
 require('./chunk-UQOBUJIQ.cjs');
 
 
-exports.Exit = _chunkGWFYZDURcjs.Exit;
+exports.Exit = _chunkWL7ZIMYDcjs.Exit;