llmz 0.0.12 → 0.0.14

package/dist/result.d.ts

@@ -2,32 +2,462 @@ import { Context, Iteration } from './context.js';
 import { SnapshotSignal } from './errors.js';
 import { Exit, ExitResult } from './exit.js';
 import { Snapshot } from './snapshots.js';
+/**
+ * Base class for all execution results returned by the `execute()` function.
+ *
+ * ExecutionResult provides a type-safe way to handle the different outcomes of LLMz
+ * agent execution. All results contain the execution context and provide methods
+ * to check the final status and access relevant data.
+ *
+ * ## Result Types
+ *
+ * LLMz execution can result in three different outcomes:
+ * - **Success**: Agent completed with an Exit (SuccessExecutionResult)
+ * - **Error**: Execution failed with an unrecoverable error (ErrorExecutionResult)
+ * - **Interrupted**: Execution was paused for snapshots or cancellation (PartialExecutionResult)
+ *
+ * ## Usage Patterns
+ *
+ * ### Basic Status Checking
+ * ```typescript
+ * const result = await execute({
+ *   instructions: 'Calculate the sum of numbers 1 to 100',
+ *   client,
+ * })
+ *
+ * if (result.isSuccess()) {
+ *   console.log('Success:', result.output)
+ * } else if (result.isError()) {
+ *   console.error('Error:', result.error)
+ * } else if (result.isInterrupted()) {
+ *   console.log('Interrupted - snapshot available:', !!result.snapshot)
+ * }
+ * ```
+ *
+ * ### Type-Safe Exit Checking
+ * ```typescript
+ * const dataExit = new Exit({
+ *   name: 'dataProcessed',
+ *   schema: z.object({
+ *     recordCount: z.number(),
+ *     processingTime: z.number(),
+ *   }),
+ * })
+ *
+ * const result = await execute({
+ *   instructions: 'Process the data',
+ *   exits: [dataExit],
+ *   client,
+ * })
+ *
+ * // Type-safe exit checking with typed output access
+ * if (result.is(dataExit)) {
+ *   console.log(`Processed ${result.output.recordCount} records`)
+ *   console.log(`Processing took ${result.output.processingTime}ms`)
+ * }
+ * ```
+ *
+ * ### Accessing Execution Details
+ * ```typescript
+ * if (result.isSuccess()) {
+ *   // Access the generated code from the final iteration
+ *   console.log('Generated code:', result.iteration.code)
+ *
+ *   // Access all iterations to see the full execution flow
+ *   result.iterations.forEach((iteration, index) => {
+ *     console.log(`Iteration ${index + 1}:`, iteration.status.type)
+ *   })
+ *
+ *   // Access execution context
+ *   console.log('Original instructions:', result.context.instructions)
+ * }
+ * ```
+ *
+ * ### Snapshot Handling
+ * ```typescript
+ * if (result.isInterrupted()) {
+ *   // Serialize snapshot for persistence
+ *   const serialized = result.snapshot.toJSON()
+ *   await database.saveSnapshot(serialized)
+ *
+ *   // Later, resume from snapshot
+ *   const snapshot = Snapshot.fromJSON(serialized)
+ *   snapshot.resolve({ data: 'resolved data' })
+ *
+ *   const continuation = await execute({
+ *     snapshot,
+ *     instructions: result.context.instructions,
+ *     tools: result.context.tools,
+ *     exits: result.context.exits,
+ *     client,
+ *   })
+ * }
+ * ```
+ *
+ * @see {@link SuccessExecutionResult} For successful execution results
+ * @see {@link ErrorExecutionResult} For failed execution results
+ * @see {@link PartialExecutionResult} For interrupted execution results
+ */
 export declare abstract class ExecutionResult {
     readonly status: 'success' | 'error' | 'interrupted';
     readonly context: Context;
     protected constructor(status: 'success' | 'error' | 'interrupted', context: Context);
+    /**
+     * Type guard to check if the execution completed successfully.
+     *
+     * @returns True if the execution completed with an Exit, false otherwise
+     * @example
+     * ```typescript
+     * const result = await execute({ ... })
+     *
+     * if (result.isSuccess()) {
+     *   // TypeScript knows this is SuccessExecutionResult
+     *   console.log('Output:', result.output)
+     *   console.log('Exit name:', result.result.exit.name)
+     * }
+     * ```
+     */
     isSuccess(): this is SuccessExecutionResult;
+    /**
+     * Type guard to check if the execution failed with an error.
+     *
+     * @returns True if the execution failed with an unrecoverable error, false otherwise
+     * @example
+     * ```typescript
+     * const result = await execute({ ... })
+     *
+     * if (result.isError()) {
+     *   // TypeScript knows this is ErrorExecutionResult
+     *   console.error('Execution failed:', result.error)
+     *
+     *   // Access error details from the last iteration
+     *   const lastIteration = result.iteration
+     *   if (lastIteration?.status.type === 'execution_error') {
+     *     console.error('Stack trace:', lastIteration.status.execution_error.stack)
+     *   }
+     * }
+     * ```
+     */
     isError(): this is ErrorExecutionResult;
+    /**
+     * Type guard to check if the execution was interrupted.
+     * Interrupted means there's a snapshot available and the execution was paused and needs resuming.
+     *
+     * @returns True if the execution was interrupted, false otherwise
+     * @example
+     * ```typescript
+     * const result = await execute({ ... })
+     *
+     * if (result.isInterrupted()) {
+     *   // TypeScript knows this is PartialExecutionResult
+     *   console.log('Execution paused:', result.signal.message)
+     *
+     *   // Access snapshot for later resumption
+     *   const snapshot = result.snapshot
+     *   const serialized = snapshot.toJSON()
+     *   await storage.save('execution-state', serialized)
+     * }
+     * ```
+     */
     isInterrupted(): this is PartialExecutionResult;
+    /**
+     * Type guard to check if the execution completed with a specific exit.
+     *
+     * This method provides type-safe access to the output data based on the exit's schema.
+     * It's the recommended way to handle different exit types in complex agents.
+     *
+     * @param exit - The Exit instance to check against
+     * @returns True if the execution completed with the specified exit, false otherwise
+     * @template T - The output type of the exit
+     *
+     * @example
+     * ```typescript
+     * // Define typed exits
+     * const successExit = new Exit({
+     *   name: 'success',
+     *   schema: z.object({
+     *     message: z.string(),
+     *     count: z.number(),
+     *   }),
+     * })
+     *
+     * const errorExit = new Exit({
+     *   name: 'error',
+     *   schema: z.object({
+     *     errorCode: z.string(),
+     *     details: z.string(),
+     *   }),
+     * })
+     *
+     * const result = await execute({
+     *   instructions: 'Process the data',
+     *   exits: [successExit, errorExit],
+     *   client,
+     * })
+     *
+     * // Type-safe exit handling
+     * if (result.is(successExit)) {
+     *   // TypeScript knows result.output has { message: string, count: number }
+     *   console.log(`Success: ${result.output.message}`)
+     *   console.log(`Processed ${result.output.count} items`)
+     * } else if (result.is(errorExit)) {
+     *   // TypeScript knows result.output has { errorCode: string, details: string }
+     *   console.error(`Error ${result.output.errorCode}: ${result.output.details}`)
+     * }
+     * ```
+     */
     is<T>(exit: Exit<T>): this is SuccessExecutionResult<T>;
+    /**
+     * Gets the output data from the last successful iteration.
+     *
+     * For successful executions, returns the data produced by the exit.
+     * For failed or interrupted executions, returns null.
+     *
+     * @returns The output data for successful executions, null otherwise
+     * @example
+     * ```typescript
+     * const result = await execute({ ... })
+     *
+     * // Generic output access
+     * if (result.isSuccess()) {
+     *   console.log('Output:', result.output)
+     * }
+     *
+     * // Type-safe output access with specific exits
+     * if (result.is(myExit)) {
+     *   // result.output is now typed based on myExit's schema
+     *   console.log(result.output.specificField)
+     * }
+     * ```
+     */
     get output(): unknown | null;
+    /**
+     * Gets the most recent (last) iteration from the execution.
+     *
+     * Iterations represent individual steps in the execution loop where the LLM
+     * generates code, executes it, and processes the results. The last iteration
+     * contains the final generated code and execution status.
+     *
+     * @returns The last iteration, or null if no iterations were completed
+     * @example
+     * ```typescript
+     * const result = await execute({ ... })
+     *
+     * const lastIteration = result.iteration
+     * if (lastIteration) {
+     *   console.log('Generated code:', lastIteration.code)
+     *   console.log('Status:', lastIteration.status.type)
+     *   console.log('Variables:', lastIteration.variables)
+     *   console.log('Tool calls:', lastIteration.toolCalls)
+     * }
+     * ```
+     */
     get iteration(): Iteration | null;
+    /**
+     * Gets all iterations from the execution.
+     *
+     * This provides access to the complete execution history, showing how the agent
+     * progressed through multiple iterations to reach the final result. Useful for
+     * debugging, logging, or understanding the agent's reasoning process.
+     *
+     * @returns Array of all iterations in execution order
+     * @example
+     * ```typescript
+     * const result = await execute({ ... })
+     *
+     * // Analyze the full execution flow
+     * result.iterations.forEach((iteration, index) => {
+     *   console.log(`Iteration ${index + 1}:`)
+     *   console.log('  Status:', iteration.status.type)
+     *   console.log('  Code length:', iteration.code?.length || 0)
+     *   console.log('  Tool calls:', iteration.toolCalls.length)
+     *   console.log('  Variables:', Object.keys(iteration.variables).length)
+     * })
+     *
+     * // Find iterations with specific characteristics
+     * const iterationsWithErrors = result.iterations.filter(
+     *   iter => iter.status.type === 'execution_error'
+     * )
+     *
+     * // Calculate total execution time
+     * const totalTime = result.iterations.reduce(
+     *   (sum, iter) => sum + (iter.duration || 0), 0
+     * )
+     * ```
+     */
     get iterations(): Iteration[];
 }
+/**
+ * Result for successful executions that completed with an Exit.
+ *
+ * SuccessExecutionResult indicates that the agent successfully completed its task
+ * and returned structured data through one of the provided exits. This is the
+ * most common positive outcome for LLMz executions.
+ *
+ * In *Worker Mode* (ie. no `chat` provided), if no exits were provided, the "DefaultExit" will be used.
+ * If *Chat Mode* is enabled, most likely the "ListenExit" will be used if no exits were provided.
+ *
+ * You can check for a specific exit using the `is()` method, which provides type-safe access to the output data of the exit.
+ * You can import "ListenExit" and "DefaultExit" from `llmz`.
+ *
+ * @template TOutput - The type of the output data based on the exit schema
+ *
+ * @example
+ * ```typescript
+ * import { execute, Exit, DefaultExit, ListenExit } from 'llmz'
+ *
+ * const exit = new Exit({
+ *   name: 'dataProcessed',
+ *   schema: z.object({
+ *     recordCount: z.number(),
+ *     summary: z.string(),
+ *   }),
+ * })
+ *
+ * const result = await execute({
+ *   instructions: 'Process the user data',
+ *   exits: [exit],
+ *   client,
+ * })
+ *
+ * if (result.isSuccess() && result.is(exit)) {
+ *   // Access the exit information
+ *   console.log('Exit name:', result.result.exit.name)
+ *
+ *   // Access typed output data
+ *   console.log('Records processed:', result.output.recordCount)
+ *   console.log('Summary:', result.output.summary)
+ *
+ *   // Access the final iteration (guaranteed to exist)
+ *   console.log('Generated code:', result.iteration.code)
+ * }
+ * ```
+ */
 export declare class SuccessExecutionResult<TOutput = unknown> extends ExecutionResult {
     readonly result: ExitResult<TOutput>;
     constructor(context: Context, result: ExitResult<TOutput>);
+    /**
+     * Gets the typed output data from the successful execution.
+     *
+     * This overrides the base class output property to provide proper typing
+     * based on the exit schema. The output is guaranteed to match the schema
+     * of the exit that was triggered.
+     *
+     * @returns The typed output data
+     */
     get output(): TOutput;
+    /**
+     * Gets the final iteration from the successful execution.
+     *
+     * For successful executions, there is always at least one iteration,
+     * so this method returns the guaranteed non-null final iteration.
+     *
+     * @returns The final iteration (guaranteed to exist)
+     */
     get iteration(): Iteration;
 }
+/**
+ * Result for executions that failed with an unrecoverable error.
+ *
+ * ErrorExecutionResult indicates that the execution encountered an error that could not be recovered from, such as:
+ * - Execution has been aborted by the user (eg. via the `signal` AbortSignal parameter)
+ * - Iterations exceeded the maximum allowed limit
+ *
+ * Upon iteration failure, the execution will continue until the maximum iteration limit is reached or an exit is triggered.
+ *
+ * @example
+ * ```typescript
+ * const result = await execute({
+ *   instructions: 'Call a non-existent function',
+ *   client,
+ * })
+ *
+ * if (result.isError()) {
+ *   console.error('Execution failed:', result.error)
+ *
+ *   // Access error details from the last iteration
+ *   const lastIteration = result.iteration
+ *   if (lastIteration?.status.type === 'execution_error') {
+ *     console.error('Error type:', lastIteration.status.execution_error.type)
+ *     console.error('Stack trace:', lastIteration.status.execution_error.stack)
+ *     console.error('Generated code:', lastIteration.code)
+ *   }
+ *
+ *   // Access all iterations to understand the failure progression
+ *   console.log('Total iterations before failure:', result.iterations.length)
+ * }
+ * ```
+ */
 export declare class ErrorExecutionResult extends ExecutionResult {
     readonly error: unknown;
     constructor(context: Context, error: unknown);
+    /**
+     * Gets the output data (always null for error results).
+     *
+     * @returns Always null since error executions don't produce output
+     */
     get output(): null;
 }
+/**
+ * Result for executions that were interrupted before completion.
+ *
+ * PartialExecutionResult indicates that a snapshot was created during the execution.
+ * Interrupted executions can be resumed using the provided snapshot.
+ *
+ * @example
+ * ```typescript
+ * // Tool that throws SnapshotSignal for long-running operations
+ * const longRunningTool = new Tool({
+ *   name: 'processLargeDataset',
+ *   async handler({ datasetId }) {
+ *     // Start background processing
+ *     const jobId = await startBackgroundJob(datasetId)
+ *
+ *     // Pause execution until job completes
+ *     throw new SnapshotSignal('Processing dataset', 'Waiting for background job completion', {
+ *       jobId,
+ *       datasetId,
+ *       startTime: Date.now(),
+ *     })
+ *   },
+ * })
+ *
+ * const result = await execute({
+ *   instructions: 'Process the large dataset',
+ *   tools: [longRunningTool],
+ *   client,
+ * })
+ *
+ * if (result.isInterrupted()) {
+ *   console.log('Execution paused:', result.signal.message)
+ *   console.log('Reason:', result.signal.longMessage)
+ *
+ *   // Serialize snapshot for later resumption
+ *   const serialized = result.snapshot.toJSON()
+ *   await database.saveSnapshot('job-123', serialized)
+ *
+ *   // Later, when the background job completes...
+ *   const snapshot = Snapshot.fromJSON(serialized)
+ *   snapshot.resolve({ jobResult: 'Processing completed successfully' })
+ *
+ *   const continuation = await execute({
+ *     snapshot,
+ *     instructions: result.context.instructions,
+ *     tools: result.context.tools,
+ *     exits: result.context.exits,
+ *     client,
+ *   })
+ * }
+ * ```
+ */
 export declare class PartialExecutionResult extends ExecutionResult {
     readonly signal: SnapshotSignal;
     readonly snapshot: Snapshot;
     constructor(context: Context, signal: SnapshotSignal, snapshot: Snapshot);
+    /**
+     * Gets the output data (always null for interrupted results).
+     *
+     * @returns Always null since interrupted executions don't produce final output
+     */
     get output(): null;
 }

package/dist/snapshots.d.ts

@@ -27,6 +27,79 @@ export declare namespace SnapshotStatuses {
         error: unknown;
     };
 }
+/**
+ * Snapshot represents a captured execution state that can be persisted and restored later.
+ *
+ * Snapshots are created when a SnapshotSignal is thrown during execution, typically from
+ * within a tool handler to pause execution for long-running operations that need to be
+ * completed asynchronously (e.g., background jobs, external API calls, user input).
+ *
+ * ## Use Cases
+ * - **Long-running operations**: Pause execution while waiting for external processes
+ * - **User interaction**: Collect input from users before continuing execution
+ * - **Resource management**: Defer expensive operations to background workers
+ * - **Workflow persistence**: Save execution state across process restarts
+ *
+ * ## Basic Usage
+ *
+ * ### Creating a Snapshot
+ * From within a tool handler, throw a SnapshotSignal to create a snapshot:
+ * ```typescript
+ * const tool = new Tool({
+ *   handler: async ({ input }) => {
+ *     // Start long-running operation
+ *     throw new SnapshotSignal('Waiting for external API response')
+ *   }
+ * })
+ * ```
+ *
+ * ### Handling Interrupted Execution
+ * ```typescript
+ * const result = await execute({ tools: [tool], ... })
+ *
+ * if (result.isInterrupted()) {
+ *   const snapshot = result.snapshot
+ *
+ *   // Serialize for persistence
+ *   const serialized = snapshot.toJSON()
+ *   await database.saveSnapshot(serialized)
+ * }
+ * ```
+ *
+ * ### Resuming from Snapshot
+ * ```typescript
+ * // Restore from persistence
+ * const serialized = await database.getSnapshot(id)
+ * const snapshot = Snapshot.fromJSON(serialized)
+ *
+ * // Resolve with the result of the long-running operation
+ * snapshot.resolve({ result: 'Operation completed!' })
+ *
+ * // Continue execution
+ * const continuation = await execute({
+ *   snapshot,
+ *   instructions: originalInstructions,
+ *   tools: originalTools,
+ *   exits: originalExits,
+ *   client
+ * })
+ * ```
+ *
+ * ## Snapshot Lifecycle
+ * 1. **Created**: When SnapshotSignal is thrown (status: pending)
+ * 2. **Serialized**: Convert to JSON for persistence with toJSON()
+ * 3. **Restored**: Recreate from JSON with fromJSON()
+ * 4. **Resolved/Rejected**: Provide result data with resolve() or reject()
+ * 5. **Resumed**: Continue execution with the resolved snapshot
+ *
+ * ## What's Captured
+ * - **Execution stack**: Current code position and call stack
+ * - **Variables**: All local variables and their values (up to size limit)
+ * - **Tool context**: Information about the tool call that triggered the snapshot
+ * - **Reason**: Human-readable description of why the snapshot was created
+ *
+ * @see {@link https://github.com/botpress/botpress/blob/master/packages/llmz/examples/14_worker_snapshot/index.ts} Example usage
+ */
 export declare class Snapshot {
     #private;
     readonly id: string;
@@ -34,6 +107,11 @@ export declare class Snapshot {
     readonly stack: string;
     readonly variables: Variable[];
     readonly toolCall?: ToolCall;
+    /**
+     * Gets the current status of the snapshot.
+     *
+     * @returns The snapshot status (pending, resolved, or rejected)
+     */
     get status(): Readonly<{
         type: "pending";
     } | {
@@ -44,7 +122,32 @@ export declare class Snapshot {
         error: unknown;
     }>;
     private constructor();
+    /**
+     * Creates a new Snapshot from a SnapshotSignal.
+     *
+     * This method is called internally by the LLMz execution engine when a SnapshotSignal
+     * is thrown during execution. It captures the current execution state including
+     * variables, stack trace, and tool context.
+     *
+     * @param signal The SnapshotSignal containing execution state
+     * @returns A new Snapshot instance in pending status
+     * @internal
+     */
     static fromSignal(signal: SnapshotSignal): Snapshot;
+    /**
+     * Serializes the snapshot to a JSON-compatible object for persistence.
+     *
+     * Use this method to save snapshots to databases, files, or other storage systems.
+     * The serialized snapshot can be restored later using fromJSON().
+     *
+     * @returns A JSON-serializable representation of the snapshot
+     * @example
+     * ```typescript
+     * const snapshot = result.snapshot
+     * const serialized = snapshot.toJSON()
+     * await database.save('snapshots', snapshot.id, serialized)
+     * ```
+     */
     toJSON(): {
         id: string;
         reason: string | undefined;
@@ -53,6 +156,20 @@ export declare class Snapshot {
         toolCall: ToolCall | undefined;
         status: SnapshotStatus;
     };
+    /**
+     * Restores a snapshot from its JSON representation.
+     *
+     * Use this method to recreate snapshots from persistent storage. The restored
+     * snapshot will maintain its original state and can be resolved/rejected as needed.
+     *
+     * @param json The serialized snapshot data from toJSON()
+     * @returns A restored Snapshot instance
+     * @example
+     * ```typescript
+     * const serialized = await database.get('snapshots', snapshotId)
+     * const snapshot = Snapshot.fromJSON(serialized)
+     * ```
+     */
     static fromJSON(json: {
         id: string;
         reason?: string;
@@ -61,9 +178,61 @@ export declare class Snapshot {
         toolCall?: ToolCall;
         status: SnapshotStatus;
     }): Snapshot;
+    /**
+     * Creates a deep copy of the snapshot.
+     *
+     * @returns A new Snapshot instance with identical data
+     */
     clone(): Snapshot;
+    /**
+     * Resets the snapshot status back to pending.
+     *
+     * This allows a previously resolved or rejected snapshot to be resolved/rejected
+     * again with different data. Useful for retry scenarios.
+     */
     reset(): void;
+    /**
+     * Resolves the snapshot with a successful result value.
+     *
+     * Call this method when the long-running operation that caused the snapshot
+     * has completed successfully. The provided value will be returned as the
+     * result of the original tool call when execution resumes.
+     *
+     * @param value The result value from the completed operation
+     * @throws Error if the snapshot is not in pending status
+     * @example
+     * ```typescript
+     * // After a background job completes
+     * const result = await backgroundJob.getResult()
+     * snapshot.resolve(result)
+     *
+     * // Continue execution
+     * const continuation = await execute({ snapshot, ... })
+     * ```
+     */
     resolve(value: any): void;
+    /**
+     * Rejects the snapshot with an error.
+     *
+     * Call this method when the long-running operation that caused the snapshot
+     * has failed or encountered an error. The provided error will be thrown
+     * when execution resumes, allowing the generated code to handle it.
+     *
+     * @param error The error that occurred during the operation
+     * @throws Error if the snapshot is not in pending status
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await externalAPI.call()
+     *   snapshot.resolve(result)
+     * } catch (error) {
+     *   snapshot.reject(error)
+     * }
+     *
+     * // Continue execution (will throw the error)
+     * const continuation = await execute({ snapshot, ... })
+     * ```
+     */
     reject(error: any): void;
 }
 export {};

package/dist/{tool-N6ODRRGH.js → tool-4AJIJ3QB.js}

@@ -1,6 +1,6 @@
 import {
   Tool
-} from "./chunk-JAGB2AOU.js";
+} from "./chunk-OKTHMXRT.js";
 import "./chunk-IH2WQFO5.js";
 import "./chunk-JKVVQN2P.js";
 import "./chunk-JQBT7UWN.js";

package/dist/{tool-QP4MVRWI.cjs → tool-NS7EGK7Z.cjs}

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkC6WNNTEVcjs = require('./chunk-C6WNNTEV.cjs');
+var _chunkKG7DT7WDcjs = require('./chunk-KG7DT7WD.cjs');
 require('./chunk-4L6D2A6O.cjs');
 require('./chunk-JDABP4SD.cjs');
 require('./chunk-IKSIOIIP.cjs');
@@ -8,4 +8,4 @@ require('./chunk-276Q6EWP.cjs');
 require('./chunk-UQOBUJIQ.cjs');
 
 
-exports.Tool = _chunkC6WNNTEVcjs.Tool;
+exports.Tool = _chunkKG7DT7WDcjs.Tool;