llmz 0.0.13 → 0.0.14

package/dist/{chunk-PRVFVXT4.js → chunk-2Z5SFF6R.js}

@@ -5,13 +5,13 @@ import {
 } from "./chunk-KH6JQYQA.js";
 import {
   Tool
-} from "./chunk-JAGB2AOU.js";
+} from "./chunk-OKTHMXRT.js";
 import {
   LoopExceededError
 } from "./chunk-JKVVQN2P.js";
 import {
   Exit
-} from "./chunk-JMSZKB4T.js";
+} from "./chunk-XAN7HQP5.js";
 import {
   assertValidComponent
 } from "./chunk-GGWM6X2K.js";
@@ -33,6 +33,11 @@ var Snapshot = class _Snapshot {
   variables;
   toolCall;
   #status;
+  /**
+   * Gets the current status of the snapshot.
+   *
+   * @returns The snapshot status (pending, resolved, or rejected)
+   */
   get status() {
     return Object.freeze({ ...this.#status });
   }
@@ -44,6 +49,17 @@ var Snapshot = class _Snapshot {
     this.toolCall = props.toolCall;
     this.#status = props.status;
   }
+  /**
+   * 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) {
     const variables = Object.entries(signal.variables).map(([name, value]) => {
       const type = extractType(value);
@@ -60,6 +76,20 @@ var Snapshot = class _Snapshot {
       status: { type: "pending" }
     });
   }
+  /**
+   * 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() {
     return {
       id: this.id,
@@ -70,6 +100,20 @@ var Snapshot = class _Snapshot {
       status: this.#status
     };
   }
+  /**
+   * 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) {
     return new _Snapshot({
       id: json.id,
@@ -80,6 +124,11 @@ var Snapshot = class _Snapshot {
       status: json.status
     });
   }
+  /**
+   * Creates a deep copy of the snapshot.
+   *
+   * @returns A new Snapshot instance with identical data
+   */
   clone() {
     return new _Snapshot({
       id: this.id,
@@ -90,15 +139,62 @@ var Snapshot = class _Snapshot {
       status: this.#status
     });
   }
+  /**
+   * 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() {
     this.#status = { type: "pending" };
   }
+  /**
+   * 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) {
     if (this.#status.type !== "pending") {
       throw new Error(`Cannot resolve snapshot because it is already settled: ${this.#status.type}`);
     }
     this.#status = { type: "resolved", value };
   }
+  /**
+   * 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) {
     if (this.#status.type !== "pending") {
       throw new Error(`Cannot reject snapshot because it is already settled: ${this.#status.type}`);
@@ -186,24 +282,201 @@ var ExecutionResult = class {
     this.status = status;
     this.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() {
     return this.status === "success" && this instanceof 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() {
     return this.status === "error" && this instanceof 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() {
     return this.status === "interrupted" && this instanceof 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(exit) {
     return this.status === "success" && this instanceof SuccessExecutionResult && this.result.exit === exit;
   }
+  /**
+   * 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() {
     return this.isSuccess() ? this.result.result : 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() {
     return this.context.iterations.at(-1) || 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() {
     return this.context.iterations ?? [];
   }
@@ -214,9 +487,26 @@ var SuccessExecutionResult = class extends ExecutionResult {
     super("success", context);
     this.result = result;
   }
+  /**
+   * 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() {
     return this.result.result;
   }
+  /**
+   * 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() {
     return this.context.iterations.at(-1);
   }
@@ -227,6 +517,11 @@ var ErrorExecutionResult = class extends ExecutionResult {
     super("error", context);
     this.error = error;
   }
+  /**
+   * Gets the output data (always null for error results).
+   *
+   * @returns Always null since error executions don't produce output
+   */
   get output() {
     return null;
   }
@@ -239,6 +534,11 @@ var PartialExecutionResult = class extends ExecutionResult {
     this.signal = signal;
     this.snapshot = snapshot;
   }
+  /**
+   * Gets the output data (always null for interrupted results).
+   *
+   * @returns Always null since interrupted executions don't produce final output
+   */
   get output() {
     return null;
   }