llmz 0.0.13 → 0.0.15

package/dist/context.d.ts

@@ -9,8 +9,8 @@ import { ObjectInstance } from './objects.js';
 import { LLMzPrompts, Prompt } from './prompts/prompt.js';
 import { Snapshot } from './snapshots.js';
 import { Tool } from './tool.js';
-import { TranscriptArray } from './transcript.js';
-import { ObjectMutation, Trace } from './types.js';
+import { Transcript, TranscriptArray } from './transcript.js';
+import { ObjectMutation, Serializable, Trace } from './types.js';
 type Model = Parameters<InstanceType<typeof Cognitive>['generateContent']>[0]['model'];
 export type IterationParameters = {
     transcript: TranscriptArray;
@@ -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;
@@ -88,7 +300,38 @@ export declare const DefaultExit: Exit<{
     error: string;
     success: false;
 }>;
-export declare class Iteration {
+export declare namespace Iteration {
+    type JSON = {
+        id: string;
+        messages: LLMzPrompts.Message[];
+        code?: string;
+        traces: Trace[];
+        variables: Record<string, any>;
+        started_ts: number;
+        ended_ts?: number;
+        status: IterationStatus;
+        mutations: ObjectMutation[];
+        llm?: {
+            started_at: number;
+            ended_at: number;
+            status: 'success' | 'error';
+            cached: boolean;
+            tokens: number;
+            spend: number;
+            output: string;
+            model: string;
+        };
+        transcript: Transcript.Message[];
+        tools: Tool.JSON[];
+        objects: ObjectInstance.JSON[];
+        exits: Exit.JSON[];
+        instructions?: string;
+        duration?: string;
+        error?: string | null;
+        isChatEnabled?: boolean;
+    };
+}
+export declare class Iteration implements Serializable<Iteration.JSON> {
     id: string;
     messages: LLMzPrompts.Message[];
     code?: string;
@@ -138,8 +381,82 @@ export declare class Iteration {
         variables: Record<string, any>;
     });
     end(status: IterationStatus): void;
+    toJSON(): {
+        id: string;
+        messages: LLMzPrompts.Message[];
+        code: string | undefined;
+        traces: import("./types.js").Traces.Trace[];
+        variables: Record<string, any>;
+        started_ts: number;
+        ended_ts: number | undefined;
+        status: IterationStatus;
+        mutations: ObjectMutation[];
+        llm: {
+            started_at: number;
+            ended_at: number;
+            status: "success" | "error";
+            cached: boolean;
+            tokens: number;
+            spend: number;
+            output: string;
+            model: string;
+        } | undefined;
+        transcript: Transcript.Message[];
+        tools: {
+            name: string;
+            aliases: string[];
+            description: string | undefined;
+            metadata: Record<string, unknown>;
+            input: import("json-schema").JSONSchema7 | undefined;
+            output: import("json-schema").JSONSchema7 | undefined;
+            staticInputValues: unknown;
+            maxRetries: number;
+        }[];
+        objects: {
+            name: string;
+            description: string | undefined;
+            properties: import("./objects.js").ObjectProperty[] | undefined;
+            tools: {
+                name: string;
+                aliases: string[];
+                description: string | undefined;
+                metadata: Record<string, unknown>;
+                input: import("json-schema").JSONSchema7 | undefined;
+                output: import("json-schema").JSONSchema7 | undefined;
+                staticInputValues: unknown;
+                maxRetries: number;
+            }[];
+            metadata: Record<string, unknown> | undefined;
+        }[];
+        exits: {
+            name: string;
+            aliases: string[];
+            description: string;
+            metadata: {
+                [x: string]: unknown;
+            };
+            schema: import("json-schema").JSONSchema7 | undefined;
+        }[];
+        instructions: string | undefined;
+        duration: string;
+        error: string | null;
+        isChatEnabled: boolean;
+    };
+}
+export declare namespace Context {
+    type JSON = {
+        id: string;
+        iterations: Iteration.JSON[];
+        iteration: number;
+        timeout: number;
+        loop: number;
+        temperature: number;
+        model?: Model;
+        metadata: Record<string, any>;
+        snapshot?: Snapshot.JSON;
+    };
 }
-export declare class Context {
+export declare class Context implements Serializable<Context.JSON> {
     id: string;
     chat?: Chat;
     instructions?: ValueOrGetter<string, Context>;
@@ -172,5 +489,96 @@ export declare class Context {
         snapshot?: Snapshot;
         timeout?: number;
     });
+    toJSON(): {
+        id: string;
+        iterations: {
+            id: string;
+            messages: LLMzPrompts.Message[];
+            code: string | undefined;
+            traces: import("./types.js").Traces.Trace[];
+            variables: Record<string, any>;
+            started_ts: number;
+            ended_ts: number | undefined;
+            status: IterationStatus;
+            mutations: ObjectMutation[];
+            llm: {
+                started_at: number;
+                ended_at: number;
+                status: "success" | "error";
+                cached: boolean;
+                tokens: number;
+                spend: number;
+                output: string;
+                model: string;
+            } | undefined;
+            transcript: Transcript.Message[];
+            tools: {
+                name: string;
+                aliases: string[];
+                description: string | undefined;
+                metadata: Record<string, unknown>;
+                input: import("json-schema").JSONSchema7 | undefined;
+                output: import("json-schema").JSONSchema7 | undefined;
+                staticInputValues: unknown;
+                maxRetries: number;
+            }[];
+            objects: {
+                name: string;
+                description: string | undefined;
+                properties: import("./objects.js").ObjectProperty[] | undefined;
+                tools: {
+                    name: string;
+                    aliases: string[];
+                    description: string | undefined;
+                    metadata: Record<string, unknown>;
+                    input: import("json-schema").JSONSchema7 | undefined;
+                    output: import("json-schema").JSONSchema7 | undefined;
+                    staticInputValues: unknown;
+                    maxRetries: number;
+                }[];
+                metadata: Record<string, unknown> | undefined;
+            }[];
+            exits: {
+                name: string;
+                aliases: string[];
+                description: string;
+                metadata: {
+                    [x: string]: unknown;
+                };
+                schema: import("json-schema").JSONSchema7 | undefined;
+            }[];
+            instructions: string | undefined;
+            duration: string;
+            error: string | null;
+            isChatEnabled: boolean;
+        }[];
+        iteration: number;
+        timeout: number;
+        loop: number;
+        temperature: number;
+        model: "best" | "fast" | `${string}:${string}` | undefined;
+        metadata: Record<string, any>;
+        snapshot: {
+            id: string;
+            reason: string | undefined;
+            stack: string;
+            variables: ({
+                name: string;
+                type: string;
+                bytes: number;
+                preview?: string;
+                value?: unknown;
+                truncated: boolean;
+            } & ({
+                truncated: true;
+                preview: string;
+            } | {
+                truncated: false;
+                value: unknown;
+            }))[];
+            toolCall: import("./errors.js").ToolCall | undefined;
+            status: import("./snapshots.js").SnapshotStatus;
+        } | undefined;
+    };
 }
 export {};

package/dist/{dual-modes-T53P72CH.js → dual-modes-7FI4T35O.js}

@@ -1,11 +1,11 @@
 import {
   DualModePrompt
-} from "./chunk-KH6JQYQA.js";
+} from "./chunk-2D2DE7CD.js";
 import "./chunk-JQBT7UWN.js";
 import "./chunk-GGWM6X2K.js";
 import "./chunk-ORQP26SZ.js";
-import "./chunk-SNDVQU5A.js";
-import "./chunk-4MNIJGK6.js";
+import "./chunk-3JYCCI4S.js";
+import "./chunk-ZORRILUV.js";
 import "./chunk-7WRN4E42.js";
 export {
   DualModePrompt

package/dist/{dual-modes-VLIGPIHX.cjs → dual-modes-OFHV2C3X.cjs}

@@ -1,12 +1,12 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkSHJDRZF5cjs = require('./chunk-SHJDRZF5.cjs');
+var _chunkPIDLNYIPcjs = require('./chunk-PIDLNYIP.cjs');
 require('./chunk-IKSIOIIP.cjs');
 require('./chunk-ZRCU35UV.cjs');
 require('./chunk-KMZDFWYZ.cjs');
-require('./chunk-JGVAZO4X.cjs');
-require('./chunk-276Q6EWP.cjs');
+require('./chunk-GZPN7RGH.cjs');
+require('./chunk-WHNOR4ZU.cjs');
 require('./chunk-UQOBUJIQ.cjs');
 
 
-exports.DualModePrompt = _chunkSHJDRZF5cjs.DualModePrompt;
+exports.DualModePrompt = _chunkPIDLNYIPcjs.DualModePrompt;

package/dist/exit-XAYKJ6TR.cjs

@@ -0,0 +1,8 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunk3G3BS5IAcjs = require('./chunk-3G3BS5IA.cjs');
+require('./chunk-WHNOR4ZU.cjs');
+require('./chunk-UQOBUJIQ.cjs');
+
+
+exports.Exit = _chunk3G3BS5IAcjs.Exit;

package/dist/{exit-YORW76T3.js → exit-YLO7BY7Z.js}

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