llmz 0.3.0 → 0.3.1

package/dist/index.cjs

@@ -69,7 +69,7 @@ var _chunkGOWPACSKcjs = require('./chunk-GOWPACSK.cjs');
 var _chunkHC2QZTVTcjs = require('./chunk-HC2QZTVT.cjs');
 
 // package.json
-var version = "0.3.0";
+var version = "0.3.1";
 
 // src/objects.ts
 var _zui = require('@bpinternal/zui');

package/dist/index.js

@@ -69,7 +69,7 @@ import {
 } from "./chunk-34GJUS6U.js";
 
 // package.json
-var version = "0.3.0";
+var version = "0.3.1";
 
 // src/objects.ts
 import { z } from "@bpinternal/zui";

package/dist/index.workerd.js

@@ -15759,7 +15759,7 @@ var init_execute = __esm({
 });
 
 // package.json
-var version = "0.3.0";
+var version = "0.3.1";
 
 // src/index.ts
 init_tool();

package/package.json

@@ -2,7 +2,11 @@
   "name": "llmz",
   "type": "module",
   "description": "LLMz - An LLM-native Typescript VM built on top of Zui",
-  "version": "0.3.0",
+  "version": "0.3.1",
+  "files": [
+    "dist",
+    "DOCS.md"
+  ],
   "types": "./dist/index.d.ts",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -64,8 +68,8 @@
     "tsx": "^4.19.2"
   },
   "peerDependencies": {
-    "@botpress/client": "1.49.0",
-    "@botpress/cognitive": "1.0.0",
+    "@botpress/client": "2.0.0",
+    "@botpress/cognitive": "1.0.1",
     "@bpinternal/thicktoken": "^3.1.0",
     "@bpinternal/zui": "^2.4.0"
   },

package/CLAUDE.md

@@ -1,362 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## What is LLMz?
-
-LLMz is a revolutionary TypeScript AI agent framework that fundamentally changes how AI agents work. Like other agent frameworks, LLMz calls LLM models in a loop to achieve desired outcomes with access to tools and memory. However, LLMz is **code-first** – meaning it generates and runs TypeScript code in a sandbox rather than using traditional JSON tool calling.
-
-**Core Philosophy**: Stop chaining tools. Start generating real code.
-
-### Why Code Generation Works Better
-
-Traditional agent frameworks rely on JSON tool calling, which has significant limitations:
-
-- Hard-to-parse JSON schemas for LLMs
-- Incapable of complex logic, loops, and conditionals
-- Multiple expensive roundtrips for each tool call
-- Unreliable beyond simple scenarios
-
-LLMz leverages the fact that models have been trained extensively on millions of TypeScript codebases, making them incredibly reliable at generating working code. This enables:
-
-- Complex logic and multi-tool orchestration in **one call**
-- Native LLM thinking via comments and code structure
-- Complete type safety and predictable schemas
-- Seamless scaling in production environments
-
-## Core Concepts
-
-### Execution Loop
-
-LLMz exposes a single method (`execute`) that runs in a loop until one of these conditions:
-
-1. **An Exit is returned** - Agent completes with structured result
-2. **Agent waits for user input** (Chat Mode) - Returns control to user
-3. **Maximum iterations reached** - Safety limit to prevent infinite loops
-
-The loop automatically handles:
-
-- Tool calling and result processing
-- Thinking about outputs and context
-- Error recovery and retry logic
-- Variable state persistence across iterations
-
-### Generated Code Structure
-
-Every LLMz code block follows a predictable structure:
-
-**Return Statement (Required)**:
-
-```tsx
-// Chat mode - give turn back to user
-return { action: 'listen' }
-
-// Worker mode - complete with result
-return { action: 'done', result: calculatedValue }
-```
-
-**Tool Calls with Logic**:
-
-```tsx
-// Complex logic impossible with JSON tool calling
-const price = await getTicketPrice({ from: 'quebec', to: 'new york' })
-
-if (price > 500) {
-  throw new Error('Price too high')
-} else {
-  const ticketId = await buyTicket({ from: 'quebec', to: 'new york' })
-  return { action: 'done', result: ticketId }
-}
-```
-
-**Comments for Planning**:
-
-```tsx
-// Comments help LLM think step-by-step and plan ahead
-// Check user's budget first before proceeding with purchase
-const budget = await getUserBudget()
-```
-
-### Execution Modes
-
-**Chat Mode**: Interactive conversational agents
-
-- Enabled when `chat` is provided to `execute()`
-- Agents can `yield` React components to user
-- Special `ListenExit` automatically available for user interaction
-- Transcript management for conversation history
-
-**Worker Mode**: Automated execution environments
-
-- Enabled when `chat` is omitted from `execute()`
-- Focus on computational tasks and data processing
-- Uses `DefaultExit` if no custom exits provided
-- Sandboxed execution with security isolation
-
-### Chat Components (Chat Mode Only)
-
-Agents can yield React components for rich user interaction:
-
-```tsx
-// Multi-line text support
-yield <Text>
-Hello, world!
-This is a second line.
-</Text>
-
-// Composed/nested components
-yield <Message>
-  <Text>What do you prefer?</Text>
-  <Button>Cats</Button>
-  <Button>Dogs</Button>
-</Message>
-
-return { action: 'listen' }
-```
-
-Components map to communication channels (Webchat, SMS, etc.) and can be completely custom.
-
-### Tools and Objects
-
-**Tools**: Type-safe functions with Zod/Zui schemas
-
-- Input/output validation and TypeScript inference
-- Synchronous and asynchronous support
-- Retry logic and error handling
-- Tool aliases for multiple names
-
-**Objects**: Namespaced containers for related tools and variables
-
-- Group related functionality together
-- Support both readonly and writable variables
-- Variable type validation with schemas
-- Mutation tracking across iterations
-
-### Advanced Features
-
-**Snapshots**: Pausable/resumable execution
-
-- Throw `SnapshotSignal` to halt and serialize execution state
-- Resume later from exact same point
-- Useful for long-running workflows and async operations
-
-**Thinking**: Agent reflection and variable inspection
-
-- Agent-initiated: `return { action: 'think' }`
-- Tool-initiated: Throw `ThinkSignal` to force reflection
-- Helps agents avoid rushed decisions and process complex information
-
-**Hooks**: Custom logic at execution points
-
-- `onTrace`: Non-blocking monitoring and logging
-- `onExit`: Validate exits and implement guardrails
-- `onBeforeExecution`: Code mutation and security checks
-- `onIterationEnd`: State augmentation between iterations
-
-## Project Overview
-
-LLMz operates as an LLM-native TypeScript VM built on top of Zui (Botpress's internal schema library), battle-tested in production powering millions of AI agents worldwide.
-
-## Architecture
-
-LLMz operates as an LLM-native TypeScript VM built on top of Zui (Botpress's internal schema library). The framework includes two primary execution modes:
-
-LLMz operates in two primary modes:
-
-- **Chat Mode**: Interactive conversational agents with tools and user interaction. Chat mode is enabled when `chat` is provided to `execute()`
-- **Worker Mode**: Automated execution environments with sandboxing and security. Worker mode is enabled when `chat` is omitted from `execute()`.
-
-### Core Components
-
-**Main Framework** (`src/`):
-
-- `llmz.ts`: Core execution engine and context management
-- `vm.ts`: Virtual machine with isolated-vm and Node.js execution environments
-- `compiler/`: TypeScript compilation pipeline with AST transformations
-- `chat.ts`: Chat interface and message handling
-- `tool.ts`: Tool definition and execution system
-- `component.ts`: UI component system for interactive elements
-
-**Execution Pipeline**:
-
-- `prompts/`: Dual-mode prompt system (chat-mode/, worker-mode/)
-- `transcript.ts`: Conversation history and context management
-- `context.ts`: Execution context and iteration tracking
-- `result.ts`: Execution result types and error handling
-
-**Safety & Security**:
-
-- `errors.ts`: Comprehensive error handling and signals
-- `stack-traces.ts`: Stack trace sanitization
-- `snapshots.ts`: Execution state snapshots
-- `truncator.ts`: Content truncation for token limits
-
-## Development Commands
-
-### Building and Testing
-
-```bash
-# Build the package (TypeScript compilation + bundling)
-pnpm build
-
-# Type checking without emitting files
-pnpm check:type
-
-# Development mode with hot reloading
-pnpm watch
-
-# Run test suite
-pnpm test
-
-# Run tests in watch mode
-pnpm test:watch
-
-# Update test snapshots
-pnpm test:update
-
-# Generate prompt files (.md.ts) files after changing them
-pnpm generate
-```
-
-### Testing Configuration
-
-- Tests use Vitest with custom configuration for LLM testing
-- Retry mechanism (2 retries) due to LLM non-determinism
-- Extended timeout (60s) for LLM response times
-- Custom snapshot serializers for stack traces
-- Markdown and text file loaders for prompt testing
-
-## Key Dependencies
-
-**Core Runtime**:
-
-- `isolated-vm`: Secure JavaScript execution environment
-- `@babel/*`: TypeScript/JSX compilation pipeline
-- `@botpress/client`: Botpress API integration
-- `@bpinternal/zui`: Schema validation and TypeScript generation
-
-**Development**:
-
-- `tsup`: Fast TypeScript bundler (ESM + CJS output)
-- `vitest`: Modern test framework with TypeScript support
-- `prettier`: Code formatting
-
-## Code Architecture Patterns
-
-### Execution Flow
-
-1. **Prompt Generation**: Dual-mode prompts based on execution type
-2. **Code Generation**: LLM generates TypeScript code with embedded tools
-3. **Compilation**: Babel-based AST transformation with custom plugins
-4. **Execution**: Isolated VM or Node.js execution with monitoring
-5. **Result Processing**: Type-safe result handling and error recovery
-
-### Key Plugins (`src/compiler/plugins/`):
-
-- `track-tool-calls.ts`: Instrument tool calls for monitoring
-- `variable-extraction.ts`: Extract and track variable usage
-- `line-tracking.ts`: Source map generation and error tracking
-- `jsx-preserve-newlines.ts`: Maintain formatting in JSX components
-
-### VM Execution Strategy
-
-- **Production**: Uses `isolated-vm` for security isolation
-- **CI/Development**: Falls back to Node.js VM for compatibility
-- **Browser**: Uses standard JavaScript execution
-
-## Tool System
-
-Tools are defined using Zui schemas and can be:
-
-- **Synchronous/Asynchronous**: Both execution types supported
-- **Type-Safe**: Full TypeScript inference and validation
-- **Retryable**: Built-in retry logic with exponential backoff
-- **Traceable**: Comprehensive execution monitoring
-
-Example tool definition:
-
-```typescript
-const tool = new Tool({
-  name: 'exampleTool',
-  description: 'Tool description',
-  input: z.object({ param: z.string() }),
-  output: z.object({ result: z.string() }),
-  handler: async ({ param }) => ({ result: `Processed: ${param}` }),
-})
-```
-
-## Component System
-
-LLMz includes a React-like component system for building interactive UIs:
-
-- **JSX Support**: Full JSX compilation and rendering
-- **Type Safety**: Components are fully typed with Zui schemas
-- **Rendering**: Server-side rendering to various output formats
-
-## Security Considerations
-
-- **Isolated Execution**: VM isolation prevents access to host system
-- **Stack Trace Cleaning**: Removes internal framework details from errors
-- **Tool Access Control**: Granular permissions for tool execution
-- **Content Truncation**: Automatic handling of token limits
-- **Error Recovery**: Graceful handling of execution failures
-
-## File Structure Conventions
-
-- Tests co-located with source files (`.test.ts` suffix)
-- Markdown prompts compiled to TypeScript modules
-- Source maps preserved for debugging
-- TypeScript declaration files generated for exports
-
-## Environment Variables
-
-- `VM_DRIVER`: Choose VM execution environment ('isolated-vm' | 'node')
-- `CI`: Automatically detected, affects VM driver selection
-
-## Performance Considerations
-
-- Code splitting with dynamic imports for faster startup
-- LRU caching for compiled code and results
-- Lazy loading of heavy dependencies
-- Bundle size optimization with tsup configuration
-
-## Exit System
-
-LLMz uses a sophisticated exit system for controlling agent termination:
-
-- **Built-in Exits**: `ThinkExit`, `ListenExit`, `DefaultExit` for common patterns
-- **Custom Exits**: Domain-specific exits with typed schemas using Zod/Zui
-- **Type Safety**: `result.is(exit)` for compile-time type checking
-- **Agent Usage**: Agents call `return { action: 'exit_name', ...data }` to exit
-
-## Prompt System Architecture
-
-The dual-mode prompt system (`src/prompts/`) generates different prompts based on execution mode:
-
-- **Chat Mode**: Uses prompts from `chat-mode/` for interactive conversations
-- **Worker Mode**: Uses prompts from `worker-mode/` for automated execution
-- **Markdown Templates**: Prompts are written in Markdown and compiled to TypeScript
-- **Dynamic Content**: Tool definitions, schemas, and context injected at runtime
-
-## Compiler Pipeline
-
-The Babel-based compilation system transforms generated code:
-
-1. **AST Parsing**: TypeScript/JSX code parsed into Abstract Syntax Tree
-2. **Plugin Transformation**: Custom plugins modify the AST for execution
-3. **Code Generation**: Modified AST compiled back to executable JavaScript
-4. **Source Maps**: Generated for debugging and error tracking
-
-Key transformations:
-
-- Tool call instrumentation for monitoring
-- Variable extraction and tracking
-- JSX component handling
-- Line number preservation for stack traces
-
-# important-instruction-reminders
-
-Do what has been asked; nothing more, nothing less.
-NEVER create files unless they're absolutely necessary for achieving your goal.
-ALWAYS prefer editing an existing file to creating a new one.
-NEVER proactively create documentation files (\*.md) or README files. Only create documentation files if explicitly requested by the User.

package/docs/TODO.md

@@ -1,919 +0,0 @@
-# How LLMz works
-
-Like many other agent frameworks, LLMz is an agentic framework that calls LLM models in a loop to achieve a desired outcome, with optional access to tools and memory.
-
-Unlike other agent frameworks, LLMz is code-first – meaning it generates and runs Typescript code in a sandbox to communicate and execute tools rather than using rudimentary JSON tool calling and text responses. This is what makes agents built on LLMz more reliable and capable than other agents.
-
-## Execution Loop
-
-At its simplest, LLMz exposes a single method (`execute`) that will run in a loop until one of the following conditions are met:
-
-- An `Exit` is returned
-- The agent waits for the user input (in Chat Mode)
-- or the maximum number of iterations has been reached
-
-The loop will iterate by calling tools, thinking about tool outputs and recovering from errors automatically.
-
-## Code Generation
-
-Unlike traditional tool-calling agents, LLMz defines tools using Typescript and runs real code in a VM.
-Concretely, that means LLMz does not require and rely on tool-calling, JSON output or any other feature of LLMs outside of text generation.
-
-Because models have been trained extensively on code bases, models are usually much better at generating working code than calling tools using JSON.
-
-### Structure of an LLMz Code Bloc
-
-#### Return statement
-
-At the minimum, an LLMz response _must_ contain a return statement with an Exit.
-
-```tsx
-// in chat mode, this gives back the turn to the user
-return { action: 'listen' }
-```
-
-```tsx
-// assuming an Exit named 'done' with output schema <number> has been declared
-return { action: 'done', result: 666 }
-```
-
-#### Tool calls
-
-Because LLMz generates standard Typescript code and because the VM has access to tools passed to `execute()`. This allows the combination of multiple tool calls, conditional logic and error handling. You'll also notice that tools are type-safe and provide an output schema, which the generated code can easily use to combine tools.
-
-```tsx
-// The user wants to fly from Quebec to New York with a max budget of $500
-const price = await getTicketPrice({ from: 'quebec', to: 'new york' })
-
-if (price > 500) {
-  throw new Error('Price too high')
-} else {
-  const ticketId = await buyTicket({ from: 'quebec', to: 'new york' })
-  return { action: 'done', result: ticketId }
-}
-```
-
-#### Comments
-
-The use of comments in the code helps the LLM to think "step-by-step" and use the tools correctly. It helps the LLM plan ahead of writing the code.
-
-#### React Components (Chat Mode)
-
-In Chat Mode, the code can `yield` React components to respond to the user. Unlike tool calls, components have many benefits.
-
-They support multi-line text:
-
-```tsx
-yield <Text>
-Hello, world!
-This is a second line.
-</Text>
-
-return { action: 'listen' }
-```
-
-And they can be composed / nested:
-
-```tsx
-yield <Message>
-	<Text>What do you prefer ?</Text>
-	<Button>Cats</Button>
-	<Button>Dogs</Button>
-</Message>
-
-return { action: 'listen' }
-```
-
-# Modes: Chat vs Worker
-
-## Chat Mode
-
-    - When using Chat Mode, you need to implement the base Chat class exported by the `llmz` package
-    - In the examples folder, we implemented a basic `CLIChat` class that provides a basic CLI-base chat application
-    - The chat class must provide 3 things:
-    	- providing/fetching the chat transcript (an array of messages in the conversation)
-    	- providing a list of components the agent can respond with (for example "text" or "button")
-    	- a `handler` to send the agent messages to the user
-    - Note that the `transcript` and `components` are called every iteration, therefore can be either static or dynamic. LLMz accepts a static property but also an async getter.
-
-### Chat Components (Chat Mode)
-
-A chat component is a type of message your agent can reply with. Typically, components should map to the messages supported by the channel the communication occurs in. For example, on Botpress Webchat, a Carousel, Card, Buttons, Text, Image, Video etc. On SMS, usually only Text and Image are supported.
-
-Because Chat Components are just React components (TSX), you can define custom components for anything. For example, you could implement a PlaneTicket component (see example 10) and render the message however you want in the channel in the `Chat` handler method.
-
-### ListenExit
-
-In chat mode, the special ListenExit is automatically added. this is what allows your agent to stop looping and wait for the user to respond. Read more about Exit below.
-
-### Transcript
-
-A transcript is an array of Transcript.Message
-
-```
-// See transcript.d.ts
-import { Transcript } from 'llmz'
-```
-
-Message types:
-
-- User: a message in the conversation coming from the user
-- Assistant: a message the agent sent in the conversation
-- Event: an event represents something that happened in the context of the conversation but isn't necessarily something the user or assistant said. It could be a user interaction event, such as button click; or a notification like an extended silence or the result of an async operation.
-- Summary: when a conversation gets too long, you can generate a summary of the conversation thus far and replace the messages by a summary message (transcript compression).
-
-## Worker Mode
-
-In worker mode, the only possible outcome is the return of one of the provided Exit (or max iteration error).
-If no Exit is passed to `execute()`, then llmz's DefaultExit will be used.
-
-# Execute Props / Input
-
-## Cancellation / Abort Signal
-
-You can provide an AbortSignal to `execute({ signal })` to abort the execution of llmz. This will immediately abort LLM requests as well as the VM sandbox code execution.
-
-## Options
-
-### Loop
-
-This is how many iterations maximum `execute` will loop before erroring when failing to `exit` gracefully.
-
-### Model
-
-This is which LLM model the cognitive client will use for the LLM generations.
-
-### Timeout
-
-This is how how long the code execution can run for in milliseconds.
-
-### Temperature
-
-This is the LLM model temperature (between 0 and 1).
-
-## Dynamic Inputs
-
-Most parameters to `execute` can be either static or dynamic.
-For example, `instructions` and `tools` can be async functions that return the parameter.
-
-```tsx
-await execute({
-    client,
-
-    // Use function-based instructions that evaluate at runtime
-    instructions: () => { return '<instructions>' }
-
-    tools: async () => {
-    	// execute async operations
-    	return [toolA, toolB]
-    }
-  })
-```
-
-# Hooks
-
-LLMz provides a comprehensive hook system that allows you to inject custom logic at various points during execution. Hooks are categorized as either blocking (execution waits) or non-blocking, and either mutation (can modify data) or non-mutation.
-
-## onTrace (non-blocking, non-mutation)
-
-Called for each trace generated during iteration. Useful for logging, debugging, or monitoring execution progress.
-
-**Characteristics:**
-
-- **Non-blocking**: Execution continues without waiting for this hook
-- **Non-mutation**: Cannot modify traces
-- **Called**: For every trace event during iteration
-
-**Usage:**
-
-```tsx
-await execute({
-  onTrace: ({ trace, iteration }) => {
-    console.log(`Iteration ${iteration}: ${trace.type}`, trace)
-  },
-  // ... other props
-})
-```
-
-**Available Trace Types:**
-
-- `abort_signal`: Abort signal received
-- `comment`: Comment found in generated code
-- `llm_call_success`: LLM generation completed successfully
-- `property`: Object property accessed or modified
-- `think_signal`: ThinkSignal thrown
-- `tool_call`: Tool executed
-- `yield`: Component yielded in chat mode
-- `log`: General logging event
-
-## onIterationEnd (blocking, non-mutation)
-
-Called after each iteration ends, regardless of status. Useful for logging, cleanup, or controlling iteration timing.
-
-**Characteristics:**
-
-- **Blocking**: Execution waits until this hook resolves
-- **Non-mutation**: Cannot modify iteration result or status
-- **Called**: After every iteration completion
-
-**Usage:**
-
-```tsx
-await execute({
-  onIterationEnd: async (iteration, controller) => {
-    console.log(`Iteration ${iteration.id} ended with status: ${iteration.status.type}`)
-
-    // Add delays, cleanup, or conditional logic
-    if (iteration.status.type === 'execution_error') {
-      await logError(iteration.error)
-    }
-
-    // Can use controller to abort execution if needed
-    // controller.abort('Custom abort reason')
-  },
-  // ... other props
-})
-```
-
-## onExit (blocking, non-mutation)
-
-Called when an exit is reached. Useful for logging, notifications, or implementing guardrails by throwing errors to prevent exit.
-
-**Characteristics:**
-
-- **Blocking**: Execution waits until this hook resolves
-- **Non-mutation**: Cannot modify exit result value
-- **Called**: When any exit is reached
-- **Guardrails**: Can throw error to prevent exit and continue iteration
-
-**Usage:**
-
-```tsx
-await execute({
-  onExit: async (result) => {
-    console.log(`Exiting with: ${result.exit.name}`, result.result)
-
-    // Implement guardrails
-    if (result.exit.name === 'approve_loan' && result.result.amount > 10000) {
-      throw new Error('Manager approval required for loans over $10,000')
-    }
-
-    // Send notifications
-    await notifyStakeholders(result)
-  },
-  // ... other props
-})
-```
-
-## onBeforeExecution (blocking, mutation)
-
-Called after LLM generates code but before execution. Allows code modification and guardrails implementation.
-
-**Characteristics:**
-
-- **Blocking**: Execution waits until this hook resolves
-- **Mutation**: Can modify the code to be executed
-- **Called**: After code generation, before VM execution
-- **Guardrails**: Can throw error to trigger new iteration
-
-**Usage:**
-
-```tsx
-await execute({
-  onBeforeExecution: async (iteration, controller) => {
-    console.log('Generated code:', iteration.code)
-
-    // Code modification
-    if (iteration.code?.includes('dangerousOperation')) {
-      return {
-        code: iteration.code.replace('dangerousOperation', 'safeOperation'),
-      }
-    }
-
-    // Guardrails - throw to prevent execution
-    if (iteration.code?.includes('forbidden')) {
-      throw new Error('Forbidden operation detected')
-    }
-
-    // Add security checks, logging, etc.
-    await auditCodeGeneration(iteration.code)
-  },
-  // ... other props
-})
-```
-
-## onBeforeTool (blocking, mutation)
-
-Called before any tool execution. Allows input modification and tool execution control.
-
-**Characteristics:**
-
-- **Blocking**: Execution waits until this hook resolves
-- **Mutation**: Can modify tool input
-- **Called**: Before every tool execution
-- **Control**: Can prevent tool execution by throwing error
-
-**Usage:**
-
-```tsx
-await execute({
-  onBeforeTool: async ({ iteration, tool, input, controller }) => {
-    console.log(`Executing tool: ${tool.name}`, input)
-
-    // Input modification
-    if (tool.name === 'sendEmail') {
-      return {
-        input: {
-          ...input,
-          subject: `[Automated] ${input.subject}`, // Add prefix
-        },
-      }
-    }
-
-    // Access control
-    if (tool.name === 'deleteFile' && !hasPermission(input.path)) {
-      throw new Error('Insufficient permissions to delete file')
-    }
-
-    // Rate limiting, validation, etc.
-    await validateToolUsage(tool, input)
-  },
-  // ... other props
-})
-```
-
-## onAfterTool (blocking, mutation)
-
-Called after tool execution. Allows output modification and post-processing.
-
-**Characteristics:**
-
-- **Blocking**: Execution waits until this hook resolves
-- **Mutation**: Can modify tool output
-- **Called**: After every tool execution
-- **Processing**: Can transform results before they reach the LLM
-
-**Usage:**
-
-```tsx
-await execute({
-  onAfterTool: async ({ iteration, tool, input, output, controller }) => {
-    console.log(`Tool ${tool.name} completed`, { input, output })
-
-    // Output modification
-    if (tool.name === 'fetchUserData') {
-      return {
-        output: {
-          ...output,
-          // Remove sensitive data before LLM sees it
-          ssn: undefined,
-          creditCard: undefined,
-        },
-      }
-    }
-
-    // Result enhancement
-    if (tool.name === 'calculatePrice') {
-      return {
-        output: {
-          ...output,
-          currency: 'USD',
-          timestamp: Date.now(),
-        },
-      }
-    }
-
-    // Logging, caching, notifications
-    await cacheResult(tool.name, input, output)
-  },
-  // ... other props
-})
-```
-
-## Hook Execution Order
-
-1. **onTrace**: Throughout execution (non-blocking)
-2. **onBeforeExecution**: After code generation, before execution
-3. **onBeforeTool**: Before each tool call
-4. **onAfterTool**: After each tool call
-5. **onExit**: When exit is reached
-6. **onIterationEnd**: After iteration completes
-
-## Best Practices
-
-- **Error Handling**: Always wrap hook logic in try-catch for production
-- **Performance**: Keep hooks lightweight, especially onTrace
-- **Security**: Use onBeforeExecution and onBeforeTool for security validation
-- **Debugging**: Leverage onTrace for comprehensive execution monitoring
-- **Guardrails**: Implement business logic validation in onExit
-- **Data Transformation**: Use onBeforeTool/onAfterTool for input/output processing
-
-# Execution Result
-
-Every call to `execute()` returns an ExecutionResult that provides type-safe access to the execution outcome. LLMz execution can result in three different types of results: Success, Error, or Interrupted.
-
-## Result Types
-
-### SuccessExecutionResult
-
-Agent completed successfully with an Exit. This is the most common positive outcome containing the structured data produced by the agent.
-
-### ErrorExecutionResult
-
-Execution failed with an unrecoverable error such as:
-
-- User aborted via AbortSignal
-- Maximum iterations exceeded without reaching an exit
-- Critical system failures
-
-### PartialExecutionResult
-
-Execution was interrupted by a SnapshotSignal for pauseable operations. Contains a snapshot that can be used to resume execution later.
-
-## Basic Status Checking
-
-Use type guard methods to safely access result data:
-
-```tsx
-const result = await execute({
-  instructions: 'Calculate the sum of numbers 1 to 100',
-  client,
-})
-
-// Check execution status
-if (result.isSuccess()) {
-  console.log('Success:', result.output)
-  console.log('Generated code:', result.iteration.code)
-} else if (result.isError()) {
-  console.error('Error:', result.error)
-  console.error('Failed iteration:', result.iteration?.error)
-} else if (result.isInterrupted()) {
-  console.log('Interrupted:', result.signal.message)
-  console.log('Snapshot available:', !!result.snapshot)
-}
-```
-
-## Type-Safe Exit Checking
-
-Use `result.is(exit)` for type-safe access to specific exit data:
-
-```tsx
-const dataExit = new Exit({
-  name: 'dataProcessed',
-  schema: z.object({
-    recordCount: z.number(),
-    processingTime: z.number(),
-  }),
-})
-
-const errorExit = new Exit({
-  name: 'processingError',
-  schema: z.object({
-    errorCode: z.string(),
-    details: z.string(),
-  }),
-})
-
-const result = await execute({
-  instructions: 'Process the data',
-  exits: [dataExit, errorExit],
-  client,
-})
-
-// Type-safe exit handling with automatic output typing
-if (result.is(dataExit)) {
-  // TypeScript knows result.output has { recordCount: number, processingTime: number }
-  console.log(`Processed ${result.output.recordCount} records`)
-  console.log(`Processing took ${result.output.processingTime}ms`)
-} else if (result.is(errorExit)) {
-  // TypeScript knows result.output has { errorCode: string, details: string }
-  console.error(`Error ${result.output.errorCode}: ${result.output.details}`)
-}
-```
-
-## Accessing Execution Details
-
-### Iterations and Execution Flow
-
-```tsx
-const result = await execute({ ... })
-
-// Access the final iteration
-const lastIteration = result.iteration
-if (lastIteration) {
-  console.log('Generated code:', lastIteration.code)
-  console.log('Status:', lastIteration.status.type)
-  console.log('Duration:', lastIteration.duration)
-}
-
-// Access all iterations to see 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('  Variables:', Object.keys(iteration.variables).length)
-})
-
-// Find specific iteration types
-const errorIterations = result.iterations.filter(
-  iter => iter.status.type === 'execution_error'
-)
-
-const thinkingIterations = result.iterations.filter(
-  iter => iter.status.type === 'thinking_requested'
-)
-```
-
-### Variables and Declarations
-
-Agent-generated variables are accessible in the iteration object:
-
-```tsx
-// If agent generates: const hello = '1234'
-const lastIteration = result.iteration
-if (lastIteration) {
-  console.log(lastIteration.variables.hello) // '1234'
-
-  // Access all variables from the final iteration
-  Object.entries(lastIteration.variables).forEach(([name, value]) => {
-    console.log(`Variable ${name}:`, value)
-  })
-}
-
-// Variables persist across thinking iterations
-result.iterations.forEach((iteration) => {
-  if (iteration.status.type === 'thinking_requested') {
-    console.log('Variables during thinking:', iteration.variables)
-  }
-})
-```
-
-### Tool Calls and Traces
-
-```tsx
-const result = await execute({ ... })
-
-// Access tool calls from all iterations
-const allToolCalls = result.iterations.flatMap(iter =>
-  iter.traces.filter(trace => trace.type === 'tool_call')
-)
-
-console.log('Total tool calls:', allToolCalls.length)
-
-// Access other trace types
-const lastIteration = result.iteration
-if (lastIteration) {
-  const yields = lastIteration.traces.filter(trace => trace.type === 'yield')
-  const comments = lastIteration.traces.filter(trace => trace.type === 'comment')
-  const propertyAccess = lastIteration.traces.filter(trace => trace.type === 'property')
-}
-```
-
-### Context and Metadata
-
-```tsx
-if (result.isSuccess()) {
-  // Access original execution parameters
-  console.log('Instructions:', result.context.instructions)
-  console.log('Loop limit:', result.context.loop)
-  console.log('Temperature:', result.context.temperature)
-  console.log('Model:', result.context.model)
-
-  // Access tools and exits that were available
-  console.log(
-    'Available tools:',
-    result.context.tools?.map((t) => t.name)
-  )
-  console.log(
-    'Available exits:',
-    result.context.exits?.map((e) => e.name)
-  )
-}
-```
-
-## Snapshot Handling (Advanced)
-
-Handle interrupted executions with snapshot resumption:
-
-```tsx
-const result = await execute({
-  instructions: 'Process large dataset with pauseable operation',
-  tools: [snapshotCapableTool],
-  client,
-})
-
-if (result.isInterrupted()) {
-  console.log('Execution paused:', result.signal.message)
-  console.log('Reason:', result.signal.longMessage)
-
-  // Serialize snapshot for persistence
-  const serialized = result.snapshot.toJSON()
-  await database.saveSnapshot('execution-123', serialized)
-
-  // Later, resume from snapshot
-  const snapshot = Snapshot.fromJSON(serialized)
-  snapshot.resolve({ resumeData: 'Operation completed' })
-
-  const continuation = await execute({
-    snapshot,
-    instructions: result.context.instructions,
-    tools: result.context.tools,
-    exits: result.context.exits,
-    client,
-  })
-
-  // Continuation will resume from exactly where it left off
-  if (continuation.isSuccess()) {
-    console.log('Resumed execution completed:', continuation.output)
-  }
-}
-```
-
-## Built-in Exits
-
-```tsx
-import { ListenExit, DefaultExit, ThinkExit } from 'llmz'
-
-const result = await execute({ ... })
-
-// Check for built-in exits
-if (result.is(ListenExit)) {
-  console.log('Agent is waiting for user input')
-}
-
-if (result.is(DefaultExit)) {
-  // DefaultExit has success/failure discriminated union
-  if (result.output.success) {
-    console.log('Completed successfully:', result.output.result)
-  } else {
-    console.error('Completed with error:', result.output.error)
-  }
-}
-
-if (result.is(ThinkExit)) {
-  console.log('Agent requested thinking time')
-  console.log('Current variables:', result.output.variables)
-}
-```
-
-## Error Analysis
-
-````tsx
-if (result.isError()) {
-  console.error('Execution failed:', result.error)
-
-  // Analyze the failure progression
-  const failedIteration = result.iteration
-  if (failedIteration) {
-    switch (failedIteration.status.type) {
-      case 'execution_error':
-        console.error('Code execution failed:', failedIteration.status.execution_error.message)
-        console.error('Stack trace:', failedIteration.status.execution_error.stack)
-        console.error('Failed code:', failedIteration.code)
-        break
-
-      case 'generation_error':
-        console.error('LLM generation failed:', failedIteration.status.generation_error.message)
-        break
-
-      case 'invalid_code_error':
-        console.error('Invalid code generated:', failedIteration.status.invalid_code_error.message)
-        console.error('Invalid code:', failedIteration.code)
-        break
-
-      case 'aborted':
-        console.error('Execution aborted:', failedIteration.status.aborted.reason)
-        break
-    }
-  }
-
-  // Review all iterations to understand failure progression
-  console.log('Iterations before failure:', result.iterations.length)
-  result.iterations.forEach((iter, i) => {
-    console.log(`Iteration ${i + 1}: ${iter.status.type}`)
-  })
-}
-
-# Tools
-
-- todo: Tool class props
-- todo: input and outpout schema
-- todo: tips: schemas and descriptions are really important for LLMz to generate good code, thus, good tool usage.
-- todo: use `tool.getTypings()` to see the code generated for the LLM
-- todo: cloning a tool and mutate the input, output, name, description or handler (see example 19, tool wrap)
-- todo: static inputs to "freeze" and force inputs on a tool
-- todo: aliases, so the same tool can be called with multiple names
-
-# Objects
-
-- todo: explain what an object is. it's like a namespace. it groups related tools together. but objects can also do more: they can contain variables.
-
-## Variables
-
-- todo: readonly vs writable variables
-- todo: variable types (schema)
-- todo: variable usage within the VM code
-- todo: type and schema validation – show an example of how the VM will throw an error when trying to assign a value to a variable that doesn't pass the schema validation. see example 09.
-- todo: tracking mutations
-- todo: persisting variables across executions
-
-## Tools
-
-- todo: identical to global tools, except they are available under the object namespace. for example `myObject.myTool()`.
-
-# Snapshots (advanced)
-
-## SnapshotSignal
-
-- todo: inside a tool, throw a SnapshotSignal to halt the execution of llmz and take a serializable snapshot of the execution.
-- todo: snapshots are built to persist the state of an executuon with the goal of resuming it in the future
-- todo: thisi s useful for long-running tools for examples, like workflows etc
-
-## Snapshot object
-
-- todo: getting the snapshot from result (result.isInterrupted() and result.snapshot)
-- todo: serialize snapshot to JSON
-- todo: restoring a snapshot from JSON
-- todo: resolve a snapshot (success)
-- todo: reject a snapshot (reject)
-
-# Thinking
-
-## ThinkSignal
-
-- todo: throw new ThinkSignal to force the iteraiton and looking at variables. this is useful for tools to force LLMs to have a look at the results before responding for example.
-
-## return { action: 'think' }
-
-- todo: special return type to think and inspect variables and iterate
-
-## Citations
-
-CitationsManager is a helper provided by LLMz to standardize the registration of sources/snippets of text and referencing them in agent responses. It's particularly useful for RAG (Retrieval-Augmented Generation) systems where you need to track the source of information and provide proper attribution.
-
-### Core Concepts
-
-Citations use rare Unicode symbols (`【】`) as markers that are unlikely to appear in natural text, making them safe to use in LLM prompts and responses. The system supports:
-
-- **Source Registration**: Register any object as a citation source
-- **Tag Generation**: Automatic creation of unique citation tags like `【0】`, `【1】`
-- **Content Processing**: Extract and clean citation tags from text
-- **Multiple Citations**: Support for multi-source citations like `【0,1,3】`
-
-### Basic Usage
-
-```tsx
-import { CitationsManager } from 'llmz'
-
-const citations = new CitationsManager()
-
-// Register sources and get citation tags
-const source1 = citations.registerSource({
-  file: 'document.pdf',
-  page: 5,
-  title: 'Company Policy'
-})
-const source2 = citations.registerSource({
-  url: 'https://example.com/article',
-  title: 'Best Practices'
-})
-
-console.log(source1.tag) // "【0】"
-console.log(source2.tag) // "【1】"
-
-// Use tags in content
-const content = `The policy states that employees must arrive on time${source1.tag}. However, best practices suggest flexibility${source2.tag}.`
-
-// Extract and process citations
-const { cleaned, citations: found } = citations.extractCitations(content, (citation) => {
-  return `[${citation.id + 1}]` // Convert to numbered format
-})
-
-console.log(cleaned) // "The policy states that employees must arrive on time[1]. However, best practices suggest flexibility[2]."
-console.log(found) // Array of citation objects with source data
-````
-
-### RAG Implementation Example
-
-Here's how citations are used in a real RAG system (from example 20):
-
-```tsx
-// Tool for searching knowledge base with citations
-const ragTool = new Tool({
-  name: 'search',
-  description: 'Searches in the knowledge base for relevant information.',
-  input: z.string().describe('The query to search in the knowledge base.'),
-  async handler(query) {
-    // Perform semantic search
-    const { passages } = await client.searchFiles({
-      query,
-      tags: { purpose: RAG_TAG },
-      limit: 20,
-      contextDepth: 3,
-      consolidate: true,
-    })
-
-    // Handle no results
-    if (!passages.length) {
-      throw new ThinkSignal(
-        'No results were found',
-        'No results were found in the knowledge bases. You can try rephrasing your question or asking something else. Do NOT answer the question as no results were found.'
-      )
-    }
-
-    // Build response with citations
-    let message: string[] = ['Here are the search results from the knowledge base:']
-    let { tag: example } = chat.citations.registerSource({}) // Example citation
-
-    // Register each retrieved passage as a source
-    for (const passage of passages) {
-      const { tag } = chat.citations.registerSource({
-        file: passage.file.key,
-        title: passage.file.tags.title,
-      })
-
-      message.push(`<${tag} file="${passage.file.key}">`)
-      message.push(`**${passage.file.tags.title}**`)
-      message.push(passage.content)
-      message.push(`</${tag}>`)
-    }
-
-    // Provide context with citation instructions
-    throw new ThinkSignal(
-      `We got the search results. When answering the question, you MUST add inline citations (eg: "Yes, the price is $10${example} ...")`,
-      message.join('\n').trim()
-    )
-  },
-})
-```
-
-### Chat Integration
-
-The CLIChat utility demonstrates how to integrate citations into chat interfaces:
-
-```tsx
-class CLIChat extends Chat {
-  public citations: CitationsManager = new CitationsManager()
-
-  private async sendMessage(input: RenderedComponent) {
-    // ... component handling ...
-
-    if (text.length > 0) {
-      let sources: string[] = []
-
-      // Extract citations and format them for display
-      const { cleaned } = this.citations.extractCitations(text, (citation) => {
-        let idx = chalk.bgGreenBright.black.bold(` ${sources.length + 1} `)
-        sources.push(`${idx}: ${JSON.stringify(citation.source)}`)
-        return `${idx}` // Replace 【0】 with [1]
-      })
-
-      // Display cleaned text and sources
-      console.log(`🤖 Agent: ${cleaned}`)
-
-      if (sources.length) {
-        console.log(chalk.dim('Citations'))
-        console.log(chalk.dim('========='))
-        console.log(chalk.dim(sources.join('\n')))
-      }
-    }
-  }
-}
-```
-
-### Advanced Features
-
-#### Multiple Citation Support
-
-```tsx
-// Agent can reference multiple sources in one citation
-const content = 'This fact is supported by multiple studies【0,1,3】'
-
-const { cleaned, citations } = manager.extractCitations(content)
-// citations array will contain entries for sources 0, 1, and 3
-```
-
-#### Object Citation Processing
-
-```tsx
-// Remove citations from complex objects
-const dataWithCitations = {
-  summary: 'The report shows positive trends【0】',
-  details: {
-    revenue: 'Increased by 15%【1】',
-    costs: 'Reduced by 8%【2】',
-  },
-}
-
-const [cleanData, extractedCitations] = manager.removeCitationsFromObject(dataWithCitations)
-// cleanData has citations removed, extractedCitations contains path + citation info
-```
-
-#### Citation Stripping
-
-```tsx
-// Remove all citation tags from content
-const textWithCitations = 'This statement【0】 has multiple【1,2】 citations.'
-const cleaned = CitationsManager.stripCitationTags(textWithCitations)
-// Result: "This statement has multiple citations."
-```

package/eslint.config.mjs

@@ -1,17 +0,0 @@
-import rootConfig from '../../eslint.config.mjs'
-
-export default [
-  ...rootConfig,
-  {
-    ignores: ['e2e/__tests__/**/*', 'tsup.config.ts', 'vitest.*.ts'],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-  },
-  {
-    ignores: ['examples/**/*'],
-  },
-]