llmz 0.0.13 → 0.0.15

package/dist/snapshots.d.ts

@@ -1,4 +1,5 @@
 import { ToolCall, SnapshotSignal } from './errors.js';
+import { Serializable } from './types.js';
 type Variable = {
     name: string;
     type: string;
@@ -27,13 +28,101 @@ export declare namespace SnapshotStatuses {
         error: unknown;
     };
 }
-export declare class Snapshot {
+export declare namespace Snapshot {
+    type JSON = {
+        id: string;
+        reason?: string;
+        stack: string;
+        variables: Variable[];
+        toolCall?: ToolCall;
+        status: SnapshotStatus;
+    };
+}
+/**
+ * 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 implements Serializable<Snapshot.JSON> {
     #private;
     readonly id: string;
     readonly reason?: string;
     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 +133,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 +167,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 +189,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-QP4MVRWI.cjs → tool-O4SFRIE4.cjs}

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

package/dist/{tool-N6ODRRGH.js → tool-PCOYOCRH.js}

@@ -1,10 +1,10 @@
 import {
   Tool
-} from "./chunk-JAGB2AOU.js";
-import "./chunk-IH2WQFO5.js";
+} from "./chunk-A7QHWVD7.js";
+import "./chunk-EE6NVDID.js";
 import "./chunk-JKVVQN2P.js";
 import "./chunk-JQBT7UWN.js";
-import "./chunk-4MNIJGK6.js";
+import "./chunk-ZORRILUV.js";
 import "./chunk-7WRN4E42.js";
 export {
   Tool