# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [v0.7.4] - 2026-02-01

### Added

#### Examples
- **Adaptive Waiting Example** - Added example demonstrating adaptive waiting patterns for agents
- **Nativity Playbook** - New nativity.pb example playbook

#### Agent System
- **Unified Message Batching** - Implemented unified RollingMessageCollector for batching all agent messages including direct and meeting broadcasts. Human messages now trigger immediate flush of pending batches for responsive interaction

#### Performance
- **FanoutCache for Concurrent Access** - Added FanoutCache to handle concurrent agent access patterns more efficiently

### Improved

#### LLM Context Management
- **Accurate Token Counting** - Refactored token counting to use tiktoken library for precise token calculations. Replaced rough estimations with accurate counts via get_messages_token_count and get_token_count utility functions
- **Trigger Evaluation Examples** - Refined trigger evaluation and yield examples in prompts for better clarity on computable vs non-computable triggers
- **Final Instructions** - Revised InterpreterPrompt final instructions to emphasize concise thinking, strict adherence to available playbooks, and clear communication of assumptions for more reliable expert-like behavior

### Changed

#### Configuration
- **BGN Playbooks Visibility** - BGN playbooks are no longer made public by default for better security and encapsulation
- **Message Batching Config** - Updated message batching configuration and package dependencies
- **Optional Return Values** - Return values are now optional in playbooks for more flexible execution patterns

#### Development
- **Stop Tracking .llm_cache_test** - Removed .llm_cache_test folder from git tracking

#### Documentation
- **README Updates** - Updated README.md with latest information

### Fixed

#### Observability
- **LangFuse Message Spans** - Fixed LangFuse spans for messages not displaying message content. Now skips LangFuse spans for EOM (End of Message) markers
- **LangFuse Token Counts** - Fixed LangFuse LLM calls not showing token counts. Introduced _llm_input_tokens dictionary to correlate input tokens between LLM start and end events with proper cleanup
- **Streaming in Conditional Blocks** - Fixed Say() calls inside generated if and else blocks not being streamed. Disabled streaming of Say() calls after indented code is detected to maintain execution consistency

#### Core Functionality
- **Playbooks Attribute Check** - Fixed potential recursion issues in BaseAgent by replacing hasattr() with direct __dict__ access when checking for 'playbooks' attribute

#### Dependencies
- **Lazy Imports** - Refactored imports in messaging_mixin.py and meeting_manager.py to use lazy imports, resolving circular dependency issues

---

## [v0.7.3] - 2025-12-19

### Added

#### Agent Communication
- **Progressive Timeout Notifications** - Agents waiting for responses had no visibility into delays. Added wait mechanism with periodic timeout checks that collects interrupt messages from other sources (user, other agents) and returns combined notification. The LLM decides whether to continue waiting or take alternative action—no hard maximum wait time

#### MCP Integration
- **MCP Playbooks Discovery** - MCP servers couldn't expose available playbooks. Added automatic playbooks discovery for MCP servers enabling dynamic capability exposure

### Improved

#### LLM Context Management
- **Message Compaction Strategy** - Improved compaction to keep only the last user message and last 2 assistant messages in full; all prior messages are compacted

#### Path Resolution
- **Relative MCP Server Paths** - MCP server paths were resolved from CWD causing issues. Changed to resolve relative paths based on location of the .pb file for consistent behavior

#### Initialization
- **Agent Initialization Timing** - Agents were initialized too late in the lifecycle. Moved agent initialization to program initialize phase for proper startup sequencing

### Changed

#### Testing & CI
- **Removed Codecov Block** - Integration tests no longer run on GitHub making coverage numbers misleading. Removed codecov configuration from CI
- **MCP Test Transport** - MCP tests used network transport unnecessarily. Updated to use memory transport for faster, more reliable tests

### Fixed

- **Multi-Agent Test Reliability** - test_multi_agent.py had flaky behavior. Fixed test stability issues

---

## [v0.7.2] - 2025-12-17

### Added

#### Telemetry & Observability
- **Event-Driven Langfuse Integration** - Direct Langfuse calls created tight coupling between business logic and telemetry. Introduced comprehensive event handler system with LangfuseEventHandler class that subscribes to semantic business events and translates them to appropriate spans, observations, and traces
- **Enhanced Trace Hierarchy** - Trace organization lacked proper nesting structure. Implemented root container observations for each agent, nested playbook spans, and trace namer observations for final trace names reflecting agent class and ID
- **Comprehensive Observability Events** - Agent lifecycle wasn't properly tracked. Added AgentCreatedEvent, MessageRoutedEvent, and WaitForMessageEvent for complete visibility into system behavior

#### Meeting System
- **Meeting Shared State** - Participants couldn't share variables across meeting contexts. Added meeting shared state functionality allowing participants to share and access variables during multi-agent coordination
- **Unified Meeting Routing** - Multiple broadcast methods caused confusion. Removed deprecated meeting broadcast methods in favor of unified routing
- **End-of-Meeting Signals** - Meetings lacked proper termination handling. Added end-of-meeting signals with better error handling
- **Immediate Broadcast Delivery** - Broadcast messages were delayed. Implemented immediate delivery for broadcast messages
- **Background Task Routing** - Meeting tasks weren't routed properly. Enhanced routing for background tasks in meetings
- **Direct Agent Class References** - Proxy-based cross-agent calls were overly complex. Replaced with direct agent class references in namespace for factory method access
- **AgentsAccessor Class** - Agent registry access was scattered. Added clean, encapsulated access to agent registries
- **Structured Message IDs** - String IDs lacked type safety. Replaced with AgentID/MeetingID types throughout the codebase
- **Participant Deduplication** - Participant lists could contain duplicates. Added deduplication for meeting participants
- **Missing MEETING INVITATION Text** - Meeting invitations lacked proper text. Added missing invitation text


#### LLM Providers
- **Non-API Key Provider Support** - Cloud providers using IAM authentication weren't supported. Added support for credential-based providers like Google Vertex AI that use gcloud authentication instead of API keys (Fixes #73)
- **Improved model selection** - Added support for Grok 4.1 Fast Non-Reasoning and Gemini 3 Flash model


#### Runtime improvements
- **Component-Based User Input Messages** - Monolithic content strings were inflexible. Refactored UserInputLLMMessage to support structured components (about_you, instruction, python_code_context, final_instructions)
- **Python Code Context Format** - JSON state blocks were verbose and harder for LLMs to work with. Replaced with Python code context showing imports, local variables, call stack, and self.state as executable Python code. Now playbooks is based on JIT coding.
- **Simplified Variable Handling** - Variable preprocessing with $ prefix was complex. LLM now generates valid Python directly (state.x = 10) with no AST transformation needed
- **Self Reference in Playbooks** - 'agent' reference was inconsistent with Python conventions. Replaced 'agent' with 'self' as primary reference in playbook execution context
- **Async LLM Chunk Processing** - Synchronous chunk processing blocked event queue for 3-15s causing multi-agent synchronization issues. Made LLM chunk processing async to enable proper message buffering
- **Integer Timestamps** - Datetime objects had performance overhead. Replaced with integer timestamps relative to program start time


### Changed

#### Execution Context
- **Trigger Instructions Use Self** - Trigger instructions referenced 'agent' inconsistently. Updated to use 'self' for current agent reference
- **last_llm_response Removed from State** - This internal value didn't belong in visible state. Removed from state variables
- **Return Just Result on Success** - Error wrapping on success was unnecessary. Now returns just the result value

#### Other improvements
- **--message Processing Order** - CLI --message flag was processed after BGN playbook. Fixed to process before BGN playbook execution
- **Program Termination on Break** - Program didn't exit when terminated. Added break out of execution if program is terminated
- **Silent Message Skipping** - Messages were silently dropped. Fixed to not silently skip messages
- **Meeting Requests as BGN Triggers** - Meeting requests were incorrectly set as BGN triggers. Fixed trigger classification
- **Unwanted BGN Triggers** - BGN triggers were added to first playbook even when not requested. Fixed trigger assignment logic

---

## [v0.7.1] - 2025-11-27

### Added

#### CLI Utilities & Scripting
- **Playbook-based CLI Utilities** - Applications need to create command-line tools without boilerplate. Added support for making CLI utilities directly from playbooks, enabling rapid development of command-line applications (Fixes #69)
- **Shebang Support** - Users want to run playbooks as scripts directly. Implemented shebang support allowing playbooks to be executed as standalone scripts (e.g., `./release_notes.pb --start v0.6.0 --end v0.7.0`)

#### Communication & Transport
- **MCP Memory Transport** - Agents need efficient in-process communication without network overhead. Added in-memory transport for MCP (Model Context Protocol) enabling fast inter-agent communicationd
- **Enhanced Streaming Say()** - Streaming output couldn't handle triple-quoted strings properly. Extended Say() to support triple-quoted strings in streaming mode for better content formatting

#### Message Handling
- **Top-Level LLM Messages** - Messages outside playbook execution weren't properly tracked. Added AssistantResponseLLMMessage support with improved message ordering to ensure LLM responses appear before execution results

#### Python Code Output
- Custom output format was hard to parse and execute. Changed output format to Python code for direct execution
- **Streaming async Python execution** - Generated Python code statements execute as soon as they have been produced in the token stream


### Improved

#### Playground Improvements
- **Dark Mode Support** - Users working in low-light environments needed better UI options. Added dark mode with improved styling for better visual experience
- **Playground Code Display** - Developers couldn't see generated code in the playground. Enhanced playground to display generated Python code for transparency and debugging
- **Better Color Schemes** - CLI output was hard to read with poor color contrast. Improved color schemes for better readability and visual hierarchy

#### Agent Communication
- **Cross-Agent Communication** - Multi-agent coordination had inefficient message passing. Improved communication protocols between agents for more reliable and efficient coordination
- **Message Handling Infrastructure** - Message handling was scattered across the codebase. Refactored core message handling with top-level LLM message support and improved logging for all communication scenarios

#### Agent Behavior
- **Concise Thinking** - Agent reasoning was verbose and inefficient. Enforced concise thinking patterns to improve reasoning clarity and reduce token usage
- **Think outside the box** - Agent now considers whether anything unusual is happening and acts to mitigate that

### Changed

#### Dependencies & Versions
- **Langfuse 2.x to 3.x Upgrade** - Langfuse library had breaking changes in new version. Upgraded langfuse from version 2.x to 3.x with updated integration code
- **Updated Project Dependencies** - Dependencies were outdated and potentially vulnerable. Updated all project dependencies to latest compatible versions
- **Moved pytest-asyncio to dev dependency** - Fixes #70

#### Configuration
- **Environment Loading from CWD** - Environment variables were loaded from package root instead of current directory. Changed .env loading to use current working directory for better project isolation

#### Output & Formatting
- **Public.json Parsing** - public.json was incorrectly parsed as Python code. Fixed parsing to treat public.json as JSON format

### Fixed

#### Core Functionality
- **EndProgram() Execution** - EndProgram() wasn't properly terminating execution. Fixed EndProgram() function to correctly signal program termination
- **BGN Processing Exceptions** - Exceptions during background processing weren't handled. Implemented proper exception handling during BGN (beginning) processing
- **MCP Server Agent Busy State** - MCP server agent wasn't tracking busy state properly. Fixed busy state tracking to enable clean program exit when processing completes

#### Execution & Exit Behavior
- **Graceful Agent Shutdown** - Program exited before agents finished processing. Implemented wait for all agents to become idle before gracefully exiting
- **Non-Interactive Mode Exit Codes** - Exit codes weren't consistent in non-interactive mode. Fixed exit code handling with proper InteractiveInputRequired exception support (exit code 3)
- **Agent Instance Creation** - Agent instance creation wasn't reliable. Fixed agent instance request mechanism and ensured BGN playbooks are properly marked as public

#### Message & Context Management
- **LLM Context Duplication** - WaitForMessage calls were repeated in LLM context. Fixed to prevent duplicate WaitForMessage calls in LLM context
- **Message Ordering** - Execution results appeared before LLM responses. Fixed message ordering to ensure LLM response appears before execution results
- **Streaming Consistency** - Streaming behavior was inconsistent between modes. Fixed streaming observer to properly track streams in both interactive and non-interactive modes

---

## [v0.7.0] - 2025-11-10

### Added

#### Multi-Human Support (Fixes #62)
- **Declarative Human Agent Syntax** - Applications often need to coordinate multiple human users (e.g., customer service scenarios with customers and agents, or meetings with multiple stakeholders). Added `# Name:Human` agent type annotations in playbook headers to declare human agents explicitly, making multi-user coordination a first-class concept in the framework.
- **Per-Human Delivery Preferences** - Different humans have different interaction needs (some want real-time streaming, others prefer buffered messages). Implemented configurable delivery preferences per human agent, allowing fine-grained control over how messages are delivered to each participant.
- **Targeted Streaming** - In multi-human scenarios, not everyone needs to see every message in real-time. Added observer filtering by recipient with explicit recipient_id in stream events, enabling selective message streaming to specific participants.
- **Multi-Human Meetings** - Real-world coordination involves groups, not just pairs. Added support for meetings with multiple human participants and configurable notification preferences (all/targeted/none) to handle complex group interactions.
- **Backward Compatibility** - Existing single-user applications shouldn't break. Automatically creates a default User:Human agent when no humans are explicitly defined, ensuring seamless migration.

#### Real-Time Execution
- **Incremental Code Execution** - LLM-produced code execution had to wait until the entire code block was generated, causing delays before any processing can begin. Note that due to Say() streaming, user would see the message streaming already. Implemented incremental code parsing that executes complete Python statements as they're produced by the LLM chunk by chunk, dramatically improving perceived program responsiveness. Fixes #63
- **StreamingPythonExecutor** - Executing partial code safely requires careful boundary detection. Created a new executor that identifies complete statements incrementally as code chunks arrive, executing them immediately while buffering incomplete statements.
- **Real-Time Variable Tracking** - Users couldn't see intermediate results as the LLM reasoned through problems. Added namespace inspection to track variable changes in real-time during LLM generation, making the agent's thought process transparent.
- **Graceful Error Recovery** - Streaming execution errors would abort the entire process, losing partial work. Implemented error capture that sends streaming errors back to the LLM for intelligent retry without aborting execution, enabling self-correction via LLM.
- **Backward Walking Algorithm** - Determining valid execution boundaries in partial code is non-trivial. Implemented an algorithm that walks backwards from the last non-whitespace line to find valid executable prefixes, ensuring only complete statements are executed.

#### Observability & Debugging
- **Langfuse Additional Logging** - Debugging agent behavior required reading through logs or guessing at execution flow. Integrated comprehensive Langfuse logging for all Python capture functions (Step, Var, Artifact, Trigger, Return, Yld), providing visual execution traces. Fixes #64
- **Enhanced Readability** - Generic span names made traces hard to follow. Step content is now included in Step() span names (e.g., "Step: Calculate total price"), dramatically improving trace readability.
- **Snoop Mode** - Multi-agent communication was invisible during development, making debugging difficult. Added `--snoop` CLI flag and agent_chat debugging to observe all agent message exchanges in real-time.

#### Type Safety & Architecture
- **Type-Safe Identifiers** - Agent and Meeting IDs were stringly-typed, leading to parsing bugs and unclear code. Created identifiers.py with structured AgentID and MeetingID types, providing compile-time safety and clear semantics.
- **Elimination of String IDs** - 250+ lines of brittle string parsing code was error-prone and hard to maintain. Removed all stringly-typed ID parsing by migrating to structured identifier types.
- **Structured ID Operations** - Common operations like equality and hashing were inconsistent with string IDs. Implemented type-safe equality, hashing, and string conversion on identifier types for reliable behavior.
- **DeliveryPreferences Configuration** - Delivery behavior was scattered across the codebase. Created delivery_preferences.py to centralize and make explicit all delivery control configuration.
- **HumanState System** - Human agents don't need the complex state that AI agents maintain, wasting memory. Implemented minimal state tracking for human agents, reducing memory footprint by 90% vs AI agents.
- **StreamResult Flow Control** - Streaming control flow was implicit and confusing. Added explicit streaming control flow with new stream_result.py module for clear, maintainable streaming logic.

### Improved

#### Event-Driven Architecture
- **Asyncio Event Coordination** - Polling loops consumed CPU and added latency to message delivery. Replaced all polling loops with asyncio.Event throughout the system, eliminating busy-waiting and reducing latency.
- **Atomic Channel Creation** - Race conditions during concurrent channel creation caused message loss. Implemented atomic channel initialization that's race condition-free, ensuring reliable message delivery.
- **Error Isolation** - Errors in one callback could cascade and crash the entire system. Properly isolated callback errors to prevent cascade failures while maintaining system stability.
- **Single Message Queue** - Dual buffer system added complexity and potential for message reordering. Eliminated dual buffers in favor of a single message queue for cleaner, more predictable message routing.
- **Observer Pattern Enhancement** - Determining which observers should receive messages required complex logic. Added Meeting.should_stream_to_human() logic for explicit, declarative targeted streaming decisions.

#### Caching & Performance
- **Stack Frame Based Caching** - Type-based caching missed optimization opportunities across execution contexts. Switched to frame-based LLM message caching where the last message in each call stack frame is marked for caching, maximizing cache prefix reuse. Fixes #66

#### Message & Context Management
- **User Instruction Compaction** - Long conversations filled context windows with repeated instructions. Implemented instruction compression to improve context window utilization without losing critical information.
- **Compact Message Format** - Verbose message formatting wasted tokens. Use compact message format in LLM context for better token efficiency and reduced API costs.
- **Message Format Consistency** - Streaming and non-streaming modes produced different message formats, complicating downstream code. Fixed format differences to ensure consistent message structure regardless of delivery mode.

#### Code Quality & Organization
- **Code Reorganization** - Organic growth led to unclear module boundaries and circular dependencies. Major restructuring with git mv to establish clear separation of concerns and better project layout.
- **Absolute Path Imports** - Mix of relative and absolute imports caused confusion and import errors. Standardized on absolute imports throughout codebase for clarity and reliability.
- **Test Organization** - Tests were scattered and hard to navigate. Comprehensive test suite reorganization with consistent structure and fixed path references.
- **Unit Test Isolation** - Tests making LLM calls were slow, expensive, and non-deterministic. Disallow LLM calls from unit tests to ensure fast, deterministic testing.
- **SpecUtils Module Removal** - Deprecated SpecUtils module lingered, causing confusion. Cleaned up deprecated code to reduce maintenance burden.

#### Agent System
- **Dynamic HumanAgent Factory** - Creating human agent instances required repetitive boilerplate. Implemented subclass factory for creating human agent instances dynamically based on configuration.
- **Clean Message Routing** - String-based routing was error-prone and hard to debug. Simplified routing with structured identifiers for clear, type-safe message delivery.
- **Agent Instance Targeting** - Could only target agent classes, not specific instances. Added ability to call playbooks on specific agent instances for fine-grained control, e.g. `AccountantExpert["agent 1020"].TaxRateQuery()`. Fixes #67
#### Execution & Error Handling
- **Python Execution Errors** - Execution errors terminated processing without giving the LLM a chance to fix them. Send execution errors back to LLM for intelligent retry, enabling self-healing execution.
- **UnboundLocalError Handling** - Reading variables before assignment caused cryptic errors. Fixed to properly detect and report when variables are read before being assigned.
- **End-of-Message Handling** - EOM markers weren't consistently handled across communication types. Implemented proper EOM handling in all communication channels.
- **ReAct Mode Auto-Selection** - Users had to manually specify execution_mode even for simple cases. Automatically set execution_mode:react when no Steps specified and no execution_mode given.

#### Developer Experience
- **VSCode Launch Configuration** - Updated launch.json to enable snoop by default for better out-of-box debugging experience.
- **Improved Error Context** - Stack traces were missing for some error conditions. Enhanced error logging with complete stack traces for all error paths.
- **Streaming Infrastructure** - Stream events lacked context about recipients and meetings. Stream events now include recipient_id and meeting_id for proper filtering and routing.

### Changed

- **Default Model** - Switched to claude-haiku-4.5 for faster execution while maintaining quality for most use cases.
- **Artifact Auto-Creation** - Long variable values cluttered the prompt unnecessarily. Auto-create artifacts from Var() for values exceeding length threshold, keeping prompts clean.
- **Execution Summary Format** - Execution summaries as text were hard to browse and analyze. Playbooks execution summary now provided as structured artifact for better navigation.
- **Channel Communication** - Separate code paths for 1-on-1 vs group communication added complexity. Universal channel handles any number of participants (1, 2, or N) with single, consistent API. Fixes #65
- **Unified Communication Interface** - Three separate classes for direct messages, conversations, and meetings caused code duplication. Single Channel class handles all communication types with unified interface.
- **Message Delivery** - Hard-coded delivery logic made it difficult to add new delivery methods. Polymorphic delivery via Participant interface enables flexible, extensible delivery mechanisms.
- **Agent Arguments** - Arguments weren't available during streaming execution. Extract playbook args before LLM call to make them available during streaming for more intelligent execution.
- **Format Improvements** - Inconsistent formatting made code harder to read. Various formatting improvements for better readability and maintainability.

### Fixed

- **Streaming in CLI** - Streaming mode was enabled but no messages appeared in CLI. Fixed message display in CLI when streaming is enabled.
- **Message Format Consistency** - Streaming and non-streaming produced different JSON structures, breaking downstream code. Unified message formats between streaming and non-streaming modes.
- **Meeting Invitations** - Meeting invitations weren't properly delivered or acknowledged. Fixed invitation handling and acceptance flow for reliable meeting coordination.
- **Human Meeting Acceptance** - Humans couldn't accept meeting invitations due to state management bug. Fixed state management so humans can properly accept meetings.

### Removed

- **Deprecated SpecUtils** - SpecUtils module was deprecated but not removed, causing confusion. Removed deprecated module to clean up codebase.
- **Dual Buffer System** - Dual message buffers added complexity without clear benefit. Eliminated in favor of single message queue for simpler, more maintainable code.
- **Type-Based Caching** - Type-based cache strategy was less effective than frame-based. Removed type-based caching in favor of more efficient frame-based approach.

---

## [v0.6.2] - 2025-10-30

### Added

- Python code execution model - LLMs generate Python with capture functions (Step, Say, Var, Artifact, Trigger, Return, Yld) instead of backtick directives
- Python-only agents (Fixes #43)
- `python_executor.py` with PythonExecutor and capture functions
- `agent_proxy.py` for cross-agent communication
- Type-aware argument resolution system (Fixes #51)
  - `LiteralValue` and `VariableReference` typed wrappers
  - Playbook-type-specific resolution (external, Python, LLM)
- Variable assignment support: `$x = Func($y)` (Fixes #47)
- `$_` variable for automatic last-result capture (Fixes #52)
- Variable chaining: `Say(...) Var[$answer, $_] Return[$answer]` (Fixes #48)
- Multi-line string support with triple quotes (Fixes #55)
- String operations for artifacts (comparison, concatenation, indexing, slicing)
- Auto-load for unloaded artifacts when referenced (Fixes #59)
- Stable artifact names (Fixes #57)
- Automatic artifact creation for large results (>500 chars threshold)
- `maxTokens` and `max_llm_calls` configuration options
- Public vs private variables (underscore prefix for private)
- Type annotations in variable assignments
- Utility to compare Langfuse traces

### Changed

- Moved `Artifact` class to `variables.py` as `Variable` subclass (Fixes #50)
- Removed `llm_response_line.py` (~350 lines of regex eliminated)
- Updated `interpreter_run.txt` prompt to Python format
- Artifact threshold changed from 280 to 500 characters
- Improved streaming with placeholder resolution

### Fixed

- LoadArtifact functionality
- Parsing `true` keyword argument values
- Tests for updated `post_execute` return values

### Removed

- Backtick-based directive parsing
- `src/playbooks/artifacts.py` (consolidated into variables.py)
- Dead code cleanup

## [0.6.1] - 2025-10-11

### Added

- **LangGraph Example** - Added comprehensive tax agent implementation using LangGraph as a comparison example

### Improved

- **Error Handling** - Gracefully display missing LLM API key errors from the CLI with helpful messages
- **Dependencies** - Upgraded all dependencies to address security vulnerabilities

### Fixed

- **CreateAgent Streaming** - Fixed issue #37 where dynamically created agents using `CreateAgent()` didn't stream output properly

---

## [0.6.0] - 2025-09-27

### Added

#### Agent System & Communication
- **Dynamic Agent Creation** - New `CreateAgent()` function for instantiating agents dynamically at runtime
- **Direct Agent-to-Agent Messaging** - Improved BGN playbooks and idle loop processing for seamless inter-agent communication. Now directives such as `ask Accountant for gross salary` will work.
- **Targeted Communication** - `Say()` and `YLD` functions can now target specific agents, meetings, or users
- **Ambient Agents** - All agents now run ambiently and require explicit exit
- **Busy tracking** - Using `$_busy` variable to track if an agent is busy, so inbound messages can be handled appropriately.

#### Meeting Management
- **Meeting Playbooks** - Support for automatic and explicit meeting invitations
- **Meeting Orchestration** - Wait for required attendees with configurable timeouts
- **Meeting Broadcasting** - Messages broadcast to all attendees via meeting owner
- **Meeting Tracking** - Track and manage ongoing meetings across agents

#### Streaming & Real-time Features  
- **Progressive Streaming** - Optimistic parsing for `Say()` function enables real-time output
- **Multi-interface Streaming** - Command line, web server, and Streamlit app all support streaming
- **Async/Sync Playbooks** - Both async and sync Python playbooks are now supported

#### Configuration System
- **playbooks.toml** - Centralized configuration file for settings, including model settings with fallback support
- **Per-Agent Model Configuration** - Individual agents can have custom model configurations

#### Web Playground & Server
- **Web Server Command** - New `webserver` CLI command for running the web interface
- **Playground Command** - New `playground` CLI command with auto-opening browser support
- **Standalone Playground** - HTML-based interactive playground application for testing

#### Built-in Playbooks
- **SetVar Playbook** - New builtin function for variable assignment with return values
- **LoadFile Playbook** - Builtin function for file loading operations
- **CreateAgent Playbook** - Dynamic agent instantiation during runtime

#### Development Experience
- **Import Processor** - New `!import` directive for modular playbook composition
- **Unified Debug Logger** - Centralized debug logging with environment-driven configuration

### Improved

#### LLM & Context Management
- **Context Compaction** - Automatic LLM context compression for longer conversations
- **LLM Playbook Types** - Support for three types: `playbook` (steps), `react`, and `raw`
- **Typed Message System** - `LLMMessage` type for better prompt management
- **Playbook Description Placeholders** - Dynamic placeholder resolution in descriptions
- **Deterministic Cache Keys** - Consistent LLM caching across different environments
- **Return values** - Use expression engine for parsing return values to support expression like `Return[$amount * 2]`

#### Debugging Experience
- **VSCode Integration** - Enhanced step debugging with accurate source line mapping
- **Specific Agent Debugging** - Debug individual agents in VSCode represented as threads
- **Graceful Shutdown** - Automatic termination of debug process when client disconnects
- **Breakpoint Normalization** - Path normalization for reliable breakpoint checks

#### Markdown Playbooks
- **Semantic Message Handling** - Markdown playbooks can handle inbound messages semantically
- **Idle Loop Processing** - Enhanced idle loop and message handling capabilities
- **Source Preservation** - Original markdown preserved for accurate line numbers during debugging
- **H2 Block Separation** - Visual separators after each H2 block in .pbasm for better readability

#### Architecture & Performance
- **Event System Unification** - Merged program and debug event systems into single, cohesive architecture
- **Async EventBus** - Combined sync/async event handling with proper lifecycle management
- **Parallel Compilation** - Per-agent compilation caching with `.pbasm_cache` files
- **Variable Resolution Engine** - Enhanced expression engine for improved variable handling
- **Trigger Step Tracking** - Triggers now produce `Step[]` for better execution tracking

#### Testing & Quality
- **Test Coverage** - Overall coverage improved from 77% to 79%
- **Event System Tests** - Added 85 comprehensive tests for event types and EventBus
- **Edge Case Handling** - 97 new tests covering error conditions and edge cases

### Changed

#### System Requirements
- **Python Version** - Upgraded minimum requirement to Python 3.12

#### Event Architecture
- **Unified Events** - All events now use `agent_id` instead of `thread_id`
- **Immutable Events** - Events are now frozen dataclasses for safety
- **Single Event Module** - Debug events moved from `debug.events` to main events module

#### Compilation
- **Composite Steps** - PBAsm uses composite steps to maintain control during multi-turn conversations
- **Cache File Usage** - Compiler now uses `.pbasm_cache` files when available

### Fixed

- **Duplicate List Items** - Fixed duplicated nested list items in markdown processing
- **VSCode Thread Management** - Fixed "stopped" events for paused agents when continuing specific agent
- **Test Naming** - Renamed classes starting with "Test" to avoid pytest confusion
- **Path Issues** - Fixed path normalization for reliable breakpoint handling
- **LiteLLM Authentication** - Graceful handling of authentication errors
- **Langfuse Integration** - Tests can now run without Langfuse dependency
- **Immutable Events** - All events are now frozen dataclasses preventing accidental modification
- **Thread-Safe Configuration** - Ensured thread-safe configuration in centralized constants

### Dependencies

- **New Dependencies**:
  - `bidict` - Bidirectional dictionary support

---

## [0.5.0] - Skipped

Skipped to align with VSCode extension release 0.6.0

---

## [0.4.0] - 2025-06-15

### Added

#### MCP Integration & Agent Architecture
- **MCP Servers as Agents** - Support for Model Context Protocol servers as remote agents
- **Transport Layer** - New transport layer for MCP communication
- **Agent Class Hierarchy** - Structured hierarchy with AIAgent, LocalAIAgent, and RemoteAIAgent
- **Cross-Agent Playbook Calls** - Call playbooks across agents within the same program

#### Developer Experience
- **VSCode Debugging Support** - Full debugging integration with VSCode
- **CLI Tool** - New `playbooks` command-line interface
- **File Extension Support** - Recognition of `.pb` and `.pbc` extensions as Playbooks

#### Playbook Features
- **Metadata System** - Metadata support for agents and playbooks with public/private visibility
- **Execution Summary** - Generate playbook execution summary in `$__` variable
- **Stack-Based Context** - New context management system

### Improved

#### LLM & Caching
- **LLM Caching** - Optimized to keep only up to 4 cached messages (Anthropic max)
- **Cache Control Preservation** - Maintain cache control on system messages
- **Message Consolidation** - Consolidate messages while preserving cache control
- **Default Model** - Switched to Claude Sonnet 4.0 as default

#### Playbook Architecture
- **Class Hierarchy** - New structured hierarchy: LocalPlaybook (Markdown/Python) and RemotePlaybook
- **Async/Sync Support** - Allow both sync and async Python playbooks
- **Control Flow** - Compiler adds control flow for form filling and multi-turn conversations
- **Variable Handling** - Exclude null and private variables (starting with `$_`) from prompts

### Changed

- **Assembly Language** - Changed CLS to Assembly Language terminology
- **Compiler Prompt** - Restructured and refined compiler prompt
- **Execution Prompt** - Refined with unexpected situation examples

### Fixed

- **Variable Substitution** - Fixed issue where `Say("This $blah")` showed as "This __substituted__blah"
- **Type Setting** - Fixed setting variables with type annotations (e.g., `Var["$var1:str", "abcd"]`)
- **Python Triggers** - Ensured Python playbook triggers are processed and listed in exports.json

---

## [0.3.0] - 2025-05-04

### Added

#### Core Architecture
- **Full Reimplementation** - Complete framework rewrite for improved performance and reliability
- **JSON Output Format** - Switched from YAML to JSON for more reliable LLM output
- **Python AST Parser** - Added for function call parsing
- **Code Playbooks Triggers** - Support for triggers in code playbooks
- **RAG Retrieval Playbook** - New playbook type for retrieval-augmented generation

#### Documentation & Observability
- **GitHub Pages Documentation** - Documentation site hosted on GitHub Pages
- **Langfuse Tracing** - Integration for execution tracing and monitoring
- **Markdown Output** - Support for markdown-formatted output

#### Language Features
- **Single Playbook Mode** - Streamlined execution mode for single playbooks
- **Natural Language Programming** - Enhanced support for natural language instructions
- **Improved Conditionals** - Added ELS instruction for else branches
- **Loop Improvements** - Better loop execution with JMP instructions

### Improved

#### Execution Engine
- **Playbook Steps DAG** - Directed Acyclic Graph for step management
- **Interpreter Execution** - Major improvements to interpreter execution logic
- **Conditional Blocks** - Better handling of conditional execution blocks
- **Search Query Generation** - Improved generation of search queries
- **External Tool Calling** - Fixed and improved external tool integration

#### Developer Experience
- **Prompt Caching** - Static parts as system messages, dynamic as user messages
- **Transpiled Content** - Save to temp file for easy review
- **Test Coverage** - Expanded test suite with LLM caching
- **Base Prompt** - New base prompt for generating playbooks programs

### Changed

- **Default Model** - Changed to gpt-4o-mini for better loop handling
- **Max Iterations** - Added limits for execution iterations
- **News Mode** - Added for searching recent events
- **YAML Enforcement** - Force YAML-only mode for specific use cases

### Fixed

- **Loop Execution** - Fixed issues with loops truncating output
- **Multi-line Format** - Corrected YAML multi-line formatting
- **Step Continuation** - Fixed step numbering in loop continuations
- **Return Handling** - Fixed call stack management when returning from playbooks

---

## [0.2.0] - 2025-02-24

### Added

#### Core Features
- **Agent System** - Complete Agent and AgentChat application implementation
- **Single Playbook Mode** - New streamlined execution mode
- **Loop Support** - Full support for loops with JMP instructions
- **Multiple Tool Calls** - Support for multiple concurrent tool invocations
- **Session Management** - Session and conversation context for CLI

#### LLM & Integration
- **LiteLLM Integration** - Switched to LiteLLM for model management
- **LLM Caching** - Implemented caching with automatic cache key generation
- **Prompt Caching** - Optimized with static/dynamic message separation
- **Memory System** - Simple memory for agent threads

#### Developer Tools
- **Pre-commit Hooks** - Check .litellm_cache changes before commit
- **Test Infrastructure** - Comprehensive test suite with mocked LLM responses
- **Coverage Reporting** - Added test coverage tracking
- **Code Organization** - Major code reorganization for better structure

### Improved

- **Streaming** - Separated streaming vs non-streaming function handling
- **Error Handling** - Better handling of premature LLM yields with "continue"
- **Newline Preservation** - Maintain newlines in agent responses
- **Response Length** - Allow longer interpreter sessions for loops and procedures
- **Natural Language** - Use simpler, more natural language in prompts

### Changed

- **Default Model** - Switched to gpt-4o-mini as default
- **Python Version** - Downgraded to Python 3.10 for compatibility
- **Website Structure** - Reorganized website code under single directory
- **Test Approach** - No longer mock LLM responses due to LiteLLM cache

### Fixed

- **Loop Execution** - Fixed issues with loop continuation
- **Linter Errors** - Resolved all linting issues
- **Test Failures** - Fixed various test suite failures
- **Coverage Workflow** - Fixed GitHub Actions coverage workflow

---

## [0.1.0] - 2024-11-24

### Added

#### Foundation
- **Initial Release** - First public version of the Playbooks framework
- **Runtime Implementation** - Basic playbooks.ai runtime and hello world example
- **API Server** - REST API for playbook execution

#### Web Interface
- **Next.js Website** - Full website with landing page and playground
- **Chat Interface** - Basic chat with Claude Sonnet 3.5
- **Playbook Editor** - UI for editing playbooks
- **Playground Component** - Interactive playground for testing

#### Core Features
- **Chain of Thought** - Implementation for playbook execution
- **WebSockets Support** - Real-time communication capabilities
- **Markdown Rendering** - Support for markdown in chat interface
- **JavaScript Modules** - JS module system for browser execution

### Technical Details

- **Streaming Support** - Basic streaming implementation
