# Changelog

All notable changes to Agentbyte are documented in this file.

The format follows Keep a Changelog principles and semantic versioning.

## [0.9.0] - 2026-04-14

### Added

- Added `FinalResultPolicy` Pydantic model to the orchestration layer with `prefer_agent`, `strip_signals`, and `strip_mode` fields for explicit control over which agent message becomes the canonical `final_result`.
- Added `_generate_final_result`, `_select_final_message`, and `_strip_signals` methods to `BaseOrchestrator`, replacing the bare last-assistant-message read with a policy-driven selection algorithm.
- Wired `FinalResultPolicy` into `RoundRobinOrchestrator`, `AIOrchestrator`, and `PlanBasedOrchestrator` constructors and into all three preset builders in `agentbyte.presets`.
- Added `FinalResultPolicy` to the `agentbyte.orchestration` and root `agentbyte` public exports.
- Added `final_result` and `stop_reason` fields to `SessionMessagesResponse` so orchestrator session reloads include the persisted primary answer.
- Added orchestrator-specific final-first presentation to the WebUI: the main chat surface shows only the user prompt and `final_result`, with agent turn-taking inside a collapsible inline Thinking section.
- Added `final_result` and `stop_reason` persistence to orchestrator session metadata on both streaming and non-streaming paths in the execution engine.

### Changed

- Tightened writer preset prompt to prevent coordinator drift: writer now produces the final draft immediately without asking questions or suggesting additions.
- Tightened reviewer preset prompt to enforce binary output: reviewer outputs only the approval signal or one specific revision sentence, no production or formatting suggestions.
- Updated all three preset orchestrators to supply a `FinalResultPolicy` aligned with their control flow (TERMINATE strip for round-robin, APPROVED strip for AI-driven and plan-based).
- Updated notebook `08.1-default-presets.ipynb` and `agentbyte-plan-based-orchestration` skill to use `FinalResultPolicy` instead of the removed `prefer_final_result_from_agent` field.

### Fixed

- Fixed orchestrator `final_result` always returning the reviewer's approval signal instead of the writer's output by implementing `FinalResultPolicy.prefer_agent` selection logic.
- Fixed `_strip_signals` anywhere-mode to be truly case-insensitive using `re.IGNORECASE` instead of string replace variants.

### Breaking Changes

- Removed `ReviewGatePolicy.prefer_final_result_from_agent`. Migrate to `FinalResultPolicy(prefer_agent=...)` passed directly to the orchestrator constructor.

## [0.8.0] - 2026-04-13

### Added

- Added SQL-backed usage logging middleware with a typed persistence contract plus SQLModel-backed storage for LLM usage records.
- Added `examples/webui/in_memory.py` and `examples/webui/presets_webui.py` as concrete launchers for the packaged AgentByte WebUI.
- Added plan-based orchestration to the preset-backed WebUI catalog so round-robin, AI-driven, and plan-based teams are all selectable from the same real-entities launcher.

### Changed

- Completed the `agentbyte.webui` session contract: WebUI sessions now support `user_id`, stricter session/entity binding, and injected durable session stores for persisted `AgentContext` reload across restarts.
- Rebased and adapted the packaged WebUI frontend to AgentByte's backend contracts, including fixed session query handling, stable post-stream message refresh, richer workflow result rendering, cleaner orchestration event classification, and improved debug-panel payload inspection.
- Extended agent and orchestrator WebUI usage surfaces to show both token counts and cost estimates when providers supply pricing data.
- Removed the unused bundled examples-gallery flow and other stale picoagents-only frontend assumptions from the packaged WebUI.

### Fixed

- Fixed agent stream completion handling in the WebUI so final agent state events no longer fall through to `unknown`, immediate UI finalization works again, and post-stream session refresh reliably recalculates session totals.
- Fixed round-robin and other orchestrator debug events so lifecycle payloads render as labeled orchestration events instead of opaque `unknown` entries.
- Fixed workflow completion rendering so the WebUI shows terminal workflow outputs directly instead of dumping the raw completion envelope.

## [0.7.0] - 2026-04-09

### Added

- Added a new bundled Copilot skill: `agentbyte-fastapi-sse-streaming`, covering FastAPI native SSE setup, `ServerSentEvent` usage, and copy-ready `curl` requests for testing a running `/chat/stream` endpoint.

### Changed

- Switched `agentbyte.microwebui` from manual SSE string framing to FastAPI's native `EventSourceResponse` and `ServerSentEvent` support while keeping the existing frontend event payload contract intact.
- Refined the bundled `microwebui` frontend with a scrollable chat feed, updated visual styling, and a lightweight live "thinking" panel inside the main conversation view during streamed runs.
- Expanded the Chapter 8 web study notes to document browser-generated `session_id` / `user_id` handling, user-scoped session listing, and why `microwebui` moved from manual SSE framing to FastAPI's built-in SSE support.

## [0.6.1] - 2026-04-09

### Changed

- Improved ASCII diagrams in web study topics (`docs/study/04-web_topics/`) for better visual clarity: construction flow, session lifecycle, startup sequence, session switching, and example runtime flow now use box-drawing characters for enhanced readability.

## [0.6.0] - 2026-04-09

### Added

- Added `agentbyte.microwebui`, a new lightweight built-in web UI module for small agent demos with a simple `serve(entities=[...], port=...)` interface.
- Added a bundled vanilla frontend for `microwebui` with agent discovery, in-memory session switching, stored event-stream reload, and a live debug panel.
- Added `examples/microwebui_agents.py`, a one-file example that defines multiple agents locally and serves them through the new `microwebui` module.
- Added multiple demo agent patterns for the Chapter 8-style experience: weather, travel, and packing assistants sharing the same model client and weather tool.

### Changed

- Promoted the working Chapter 8 FastAPI + SSE prototype into the reusable `agentbyte.microwebui` package instead of keeping it only under `examples/`.
- Updated the root example run path so `make run-microwebui-example` launches the new one-file `microwebui` demo.
- Updated package build metadata so the bundled `microwebui` frontend ships in installable artifacts.

### Fixed

- Removed the redundant wheel include rule for `microwebui` UI assets, eliminating duplicate archive entries during builds while preserving install-time asset availability.
- Fixed `microwebui` request-model binding so `POST /chat/stream` accepts the frontend payload correctly after installation.
- Fixed stale in-browser session handling so a restarted server automatically falls back to a fresh in-memory session instead of repeatedly probing a dead session id.

## [0.5.0] - 2026-04-08

### Added

**Workflow Runtime Maturity (Spec 08 — eight sub-specs)**

- **Human-in-the-loop suspend/resume:** `WorkflowContext.request_input()` and `WorkflowContext.request_approval()` suspend a running workflow at any step and surface a typed `WorkflowPendingRequest`. Resume by passing `responses=` to `WorkflowRunner.run()` or `run_stream()`. Typed response coercion is automatic.
- **Checkpoint-aware pending requests:** Suspended workflows auto-save a checkpoint so pending requests survive across runner restarts. Step-level `on_checkpoint_save()` / `on_checkpoint_restore()` hooks allow steps to persist and restore private runtime state through checkpoints.
- **`SubWorkflowStep`:** First-class child workflow composition step. Runs an isolated child workflow instance per invocation, supports `input_mapper` / `output_mapper` hooks, propagates nested suspend/resume to the parent, and persists child checkpoints through parent step checkpoint hooks. Parallel parent branches using the same child definition run fully isolated.
- **`WorkflowAgent` / `workflow.as_agent()`:** Wraps any `Workflow` as a `BaseAgent`-compatible agent. Supports `full`, `last_result`, and `custom` memory modes for multi-turn history. Suspended workflows return `AgentResponse(finish_reason="suspended")` with pending-request metadata. Compatible with all orchestrators (`RoundRobinOrchestrator`, `HandoffOrchestrator`, `PlanBasedOrchestrator`).
- **Staged state semantics:** `WorkflowConfig(state_mode="staged")` opts a workflow into wave-based state commits. Steps in the same execution wave read committed state and write into step-local staged buffers; staged writes commit together after the wave drains. Conflict detection raises immediately under the default `FAIL` policy; `LAST_WRITE_WINS` picks the branch that finished last by wall-clock time.
- **Structured workflow events:** `WorkflowEventOrigin` tags distinguish framework lifecycle events (`FRAMEWORK`) from step-originated events (`STEP`). `WorkflowFailedEvent` and `StepFailedEvent` now carry `WorkflowErrorDetails` (error type, message, identifiers, traceback) instead of plain strings. All events serialise cleanly via `model_dump(mode="json")`.
- **Declarative workflow schema (`agentbyte.workflow`):** `WorkflowSchema`, `StepSchema`, `EdgeSchema`, `EdgeConditionSchema`, and `StepKind` form a fully serialisable Pydantic description of any workflow topology. `workflow_to_schema(wf)` extracts a schema from a live `Workflow` instance — no callables invoked. Fully data-driven steps (`EchoStep`, `HttpStep`) round-trip completely; code-bound steps capture `function_ref` / `agent_ref` dotted paths for registry-based reconstruction.
- **Workflow loader and builder:** `WorkflowBuilder.from_schema()` reconstructs a live `Workflow` from a `WorkflowSchema`. `WorkflowLoader` adds `from_json()`, `from_dict()`, and `from_yaml()` entry points (YAML is a soft dependency). `WorkflowStepRegistry` injects code-bound callables (`FunctionStep`, `SubWorkflowStep`, `AgentStep`) at load time. `WorkflowSchemaBuildError` is raised for unsupported reconstruction paths without a registry.
- **`TransformStep` schema round-trip:** `TransformStep` field mappings and input/output type schemas are captured as JSON Schema dicts and used to reconstruct the step without the original Python classes.

### Changed
- `WorkflowContext` is now the canonical workflow context name; the `Context` alias is removed from `agentbyte.workflow`.
- `WorkflowRunner` emits `WorkflowResumedEvent` and `StepStartedEvent` on resume paths, completing the event contract for suspended/resumed executions.
- Workflow structure hashing is now a single canonical implementation used by both the runner and checkpoint helpers, eliminating silent drift between the two code paths.

## [0.4.8] - 2026-04-06

### Added
- Added `RetryPolicy` as a public Pydantic v2 model in `agentbyte.llm`. Exported from the package root so callers can define a policy once and share it across multiple clients.
- Added `RetryMixin` as a shared retry behaviour mixin used by all four provider clients. Provides a single implementation of `_retry_with_backoff` and `_retry_stream_with_backoff` replacing the six previously duplicated methods.
- All four client constructors (`OpenAIChatCompletionClient`, `AzureOpenAIChatCompletionClient`, `OpenAIEmbeddingClient`, `AzureOpenAIEmbeddingClient`) now accept `retry_policy=` directly. All Azure auth factories (`from_api_key`, `from_default_credential`, `from_certificate`, `from_ad_token`) accept `retry_policy=` on both chat and embedding clients.
- `RetryPolicy` is now the serialized form for all four provider config classes. `dump_component()` produces a nested `retry_policy` dict; `ComponentLoader.load_component()` restores it.

### Changed
- Provider config classes (`OpenAIChatCompletionClientConfig`, `AzureOpenAIChatCompletionClientConfig`, `OpenAIEmbeddingClientConfig`, `AzureOpenAIEmbeddingClientConfig`) replace the three flat scalar fields (`max_retries`, `initial_retry_delay`, `max_retry_delay`) with a nested `retry_policy: RetryPolicy` field.
- `RetryPolicy` validation now rejects negative `max_retries`, negative delays, and configurations where `max_retry_delay < initial_retry_delay`.

### Breaking
- Component config serialization shape changed: `retry_policy` is now a nested object rather than three flat keys. Any stored component configs must be migrated to the new shape.

## [0.4.7] - 2026-04-06

### Added
- Reorganised `agentbyte.llm` into provider packages: `agentbyte.llm.openai` (chat, embedding, settings) and `agentbyte.llm.azure` (chat, embedding, settings, auth). Base classes, shared types, and pricing remain at the `llm/` root. Thin compatibility shims preserve all existing flat `agentbyte.llm.*` import paths so downstream code is unaffected.
- Added `agentbyte.llm._retry_observability` shared helper (`build_retry_record`, `build_retry_summary`). All four provider clients import from this single module so the retry record shape is defined once and consistent across providers.
- Provider-owned retry observability in chat clients: `ChatCompletionResult.metadata["retry_observability"]` is now populated by `OpenAIChatCompletionClient` and `AzureOpenAIChatCompletionClient` when at least one retry occurred; key is absent on zero retries.
- Provider-owned retry observability in embedding clients: `EmbeddingResult.metadata["retry_observability"]` is now populated by `OpenAIEmbeddingClient` and `AzureOpenAIEmbeddingClient` when at least one retry occurred; key is absent on zero retries.

### Changed
- Updated concept notebooks to reflect the new provider package layout and dual observability ownership model.
- Updated retry design doc and middleware study doc to reflect Phase 2 streaming-tool retry path and the provider vs. middleware observability split.

### Testing
- Added 11 tests in `tests/llm/test_retry_observability.py` covering absent-on-zero-retries, correct structure on one retry, and accumulation across multiple retries for all four provider client combinations (OpenAI/Azure × chat/embedding).

## [0.4.6] - 2026-04-06

### Added
- Added `RetryMiddleware` to `agentbyte.middleware` with MAF-style constructor config (`max_retries`, `initial_interval`, `backoff_factor`, `max_interval`, `jitter`, `retry_on`, `operation_types`).
- Default `operation_types` covers `tool_call` and `memory_access`; `model_call` and `embedding_call` are excluded by default to avoid nested retry with existing provider-level retry in chat and embedding clients.
- Streaming tools now retry via the shared middleware chain when a failure occurs before any user-visible output is emitted; retries are suppressed once output has started to prevent duplicate or corrupted stream output.
- Added retry observability: each retry attempt is appended to `AgentContext.metadata["retry_observability"]["history"]` with attempt number, computed delay, exception type, and outcome; a `"latest"` summary key is also updated after each operation.

### Fixed
- Fixed a pre-existing gap in `MiddlewareChain.execute_stream()` where a `None` return from `process_error()` was incorrectly treated as a recovery value, suppressing the original exception. The inline error handler now applies the same `is not None` guard already present in `_execute_error_handlers()`.

### Testing
- Added 24 unit tests in `tests/middleware/test_retry_middleware.py` covering delays, jitter, operation filtering, stream retry, hook invocation counts, and retry observability.
- Added 5 agent integration tests in `tests/agents/test_agent_retry_middleware.py` covering non-streaming tool retry, exhaustion surfacing, streaming tool pre-output retry, post-output no-retry, and approval-pause preservation.

## [0.4.5] - 2026-03-27

### Added
- Added a new `agentbyte.presets` package with provider-aware `build_chat_client()` plus default `get_*` builders for query rewriter, researcher, writer, reviewer, orchestrators, and the default workflow.
- Added a default presets example under `examples/presets/basic_presets.py`.
- Added the `notebooks/usecases/08.1-default-presets.ipynb` use-case notebook to demonstrate preset agents, orchestrators, workflows, and streaming execution.

### Changed
- Moved the role-specific `researcher -> writer -> reviewer` workflow assembly into the presets layer so `agentbyte.workflow.defaults` remains focused on generic workflow templates.
- Tightened the plan-based preset so reviewer feedback triggers writer revision and reviewer re-check loops until explicit approval is given.
- Updated the plan-based preset final result behavior to prefer the latest approved writer draft instead of the reviewer approval message.

### Testing
- Added focused preset coverage for provider resolution, preset builders, reviewer approval gating, revision-loop insertion, and final-result selection.

## [0.4.4] - 2026-03-26

### Fixed
- Corrected the release after `v0.4.3` published `0.4.2` package artifacts instead of `0.4.3`.

### Changed
- Added a mandatory release guardrail in repository instructions: clean `dist/`, rebuild with `uv build`, and verify artifact filenames/version metadata before creating or pushing a release tag.

## [0.4.3] - 2026-03-26

### Added
- Added a new Copilot skill: `agentbyte-plan-based-orchestration` for `PlanBasedOrchestrator` setup, retries, metadata, and examples.

### Changed
- Updated the `agentbyte-llm-client` skill to explain when to use `EmbeddingResult.embedding` versus `EmbeddingResult.embeddings`.

## [0.4.2] - 2026-03-25

### Added
- Added the copied picoagents `agent_framework_devui` assets under `src/agentbyte/webui/` for local parity/reference work.
- Added the upstream frontend workspace files that now live under `src/agentbyte/webui/frontend/`, including new public assets and shared UI components.

### Changed
- Replaced the previous in-repo WebUI frontend source with the picoagents frontend snapshot copied into `src/agentbyte/webui/frontend/`.
- Removed the redundant Hatch wheel `force-include` for `src/agentbyte/webui/ui`, fixing duplicate archive entries during wheel builds.

### Fixed
- Fixed PyPI publish failures caused by duplicate `agentbyte/webui/ui/*` filenames in the generated wheel.

## [0.4.1] - 2026-03-25

### Added
- Added a single-vector `embedding` field to `EmbeddingResult` while preserving the existing `embeddings`, `usage`, `model`, and `metadata` payload.

### Changed
- Updated OpenAI and Azure embedding clients so `create()` and `create_batch()` both return an `EmbeddingResult` with `embedding == embeddings[0]`.
- Shipped the packaged Chapter 8 WebUI assets and parity updates that landed after `0.4.0`.

### Testing
- Added focused embedding assertions for the dual-field result contract across OpenAI and Azure embedding clients.

## [0.4.0] - 2026-03-24

### Added
- New multi-agent orchestration module with shared `BaseOrchestrator` execution loop.
- New orchestration patterns:
  - `RoundRobinOrchestrator`
  - `AIOrchestrator`
  - `PlanBasedOrchestrator`
- New plan-based orchestration public models:
  - `PlanStep`
  - `ExecutionPlan`
  - `StepProgressEvaluation`
- New orchestration examples for basic, streaming, and OpenTelemetry-backed execution.
- New Chapter 7 study/tutorial docs for round-robin, AI-driven, and plan-based orchestration.

### Changed
- Extended orchestration execution to support focused message-list context payloads and pattern-level completion hooks.
- Improved agent-as-tool streaming telemetry so tool middleware spans are preserved for delegated agent execution.
- Added aggregate usage summaries on workflow and orchestration root spans while keeping detailed `chat ...` and `tool ...` spans at the agent/middleware layer.
- Updated study docs to clarify the telemetry boundary across agents, workflows, and orchestrators.

### Testing
- Added dedicated tests for plan-based orchestration behavior and package-level export coverage.
- Added telemetry regression coverage for delegated agent-as-tool execution and workflow root usage summaries.

## [0.3.6] - 2026-03-23

### Added
- New notebook-focused logging utility: `configure_notebook_logging()` in `agentbyte.notebook`
  - Simplifies logging setup in Jupyter notebooks
  - Always shows middleware logs at INFO level for demo visibility
  - Suppresses noisy HTTP/Azure/OpenAI logs in quiet mode by default
  - Exported from package root for easy notebook imports

### Changed
- Azure embedding client authentication simplified in notebook 02c:
  - Removed API-key auth path (certificate-only for Azure in notebooks)
  - Kept API-key auth for OpenAI embeddings
  - Notebook now supports on-the-fly model/API-version overrides

## [0.3.5] - 2026-03-18

### Added
- New async embeddings client foundation in `agentbyte.llm`:
	- `BaseEmbeddingClient`, `BaseEmbeddingClientConfig`
	- `OpenAIEmbeddingClient`, `OpenAIEmbeddingClientConfig`
	- `AzureOpenAIEmbeddingClient`, `AzureOpenAIEmbeddingClientConfig`
	- `EmbeddingResult` type export in `agentbyte.llm`.
- Separate embedding APIs for single and batch generation:
	- `create(input_text: str) -> list[float]`
	- `create_batch(input_texts: list[str]) -> list[list[float]]`

### Changed
- `AzureOpenAISettings` now supports `embedding_deployment_name` from
	`AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` for embedding client factory resolution.

### Testing
- Added focused unit tests for OpenAI and Azure embedding clients covering
	single input, batch ordering, empty input validation, and env-based factory loading.

## [0.3.4] - 2026-03-18

### Changed
- `AzureServicePrincipalSettings`: replaced `model_post_init` with a `@model_validator(mode="after")` to normalize `cognitive_scope`. All three input forms are handled: bare URL → `/.default` appended; URL ending with `/` → `.default` appended; URL already ending with `/.default` → unchanged.

## [0.3.3] - 2026-03-18
### Changed
- `AzureServicePrincipalSettings.model_post_init` now automatically appends `/.default` to `cognitive_scope` if it is not already present (e.g. `https://cognitiveservices.azure.com` → `https://cognitiveservices.azure.com/.default`).

## [0.3.2] - 2026-03-18

### Changed
- Lowered package runtime requirement from Python 3.12+ to Python 3.11+.
- Updated local interpreter pin (`.python-version`) to 3.11.
- Updated CI pipeline default Python version to 3.11 for release jobs.

### Documentation
- Updated README release metadata and installation requirements to reflect Python 3.11+ and release `0.3.2`.

## [0.3.1] - 2026-03-07

### Added
- Interactive CLI wizard: running `agentbyte` with no arguments now launches a numbered menu that guides users through command and provider selection instead of printing static help.
- `_interactive_wizard()` — two-phase prompt (command → provider) with a single re-prompt on invalid input and clean `KeyboardInterrupt` / EOFError handling.

### Changed
- `agentbyte create-skills --provider=<name>` (non-interactive / CI path) is fully preserved; the wizard is only invoked when no arguments are supplied.

## [0.3.0] - 2026-03-06

### Breaking Changes
- `BaseAgent` no longer stores a context instance. `self.context`, `reset_context()`, `clear_messages()`, `window_messages()`, and `reset()` are removed. `Agent.__init__` no longer accepts a `context=` keyword argument.
- Multi-turn sessions must now be managed by the caller: pass `context=` to each `run()`/`run_stream()` call and capture the returned context from `AgentResponse.context`.

### Changed
- `Agent.run(task=None, context=None, ...)` and `Agent.run_stream(task=None, context=None, ...)` accept a per-call `AgentContext`. When `None`, a fresh context is created automatically.
- `AgentResponse.context` returns the fully-populated working context to the caller after every run.
- `AgentAsTool.execute(parameters, context=None)` and `execute_stream(parameters, context=None, ...)` thread the caller-supplied context through to the underlying agent.
- `AgentToolCompatible` protocol updated to include `context=None` on both `execute` and `execute_stream`.

### Documentation
- `topic_agents.md`: Parts 2.5 (lock-free context threading) and 2.6 (agent-as-tool context) added.
- `topic_approval.md`: Tool approval resume pattern updated to `agent.run(context=first_response.context)`.
- `topic_otel_spans.md`: Dummy trace ID notes added; `args: {}` vs `TOOL PARAMETERS` discrepancy explained; known limitation section for parsed args not captured in chat span attributes.
- Notebooks `04-agent-with-context`, `07-agent-as-tool-coordinator`, `04.2-metadata-extraction-large-doc` updated to caller-owned context pattern.

## [0.2.7] - 2026-03-03

### Added
- `run_stream()` is now fully instrumented with an OTel root span via the native `_root_span()` context manager — every streaming task gets a correctly nested `agent <name>` root span identical to `run()`.
- New OTel example `examples/otel/agent_with_stream_telemetry.py` — streaming agent with 3 queries of increasing tool complexity (service: `agentbyte-stream`).
- New `examples/otel/inspect_traces.py` — CLI utility to inspect Jaeger traces without opening the UI; requires a traceID positional argument.

### Changed
- `auto_instrument()` now patches **only** `Agent.__init__` (OTelMiddleware injection); root span creation is handled natively in `Agent.run_stream()` — no monkey-patching of `run` or `run_stream`.
- `Agent.run_stream` execution logic renamed internally to `_run_stream_impl`; public `run_stream` is a thin span-wrapping delegate.
- `_annotate_root_span()` is a module-level function in `otel.py` — all OTel instrumentation logic is now centralized in one file.

## [0.2.6] - 2026-03-03

### Added
- OpenTelemetry model-call usage enrichment:
	- `gen_ai.usage.total_tokens`
	- `gen_ai.usage.cost_estimate_usd`
	- `gen_ai.response.finish_reason`
- Root agent span usage enrichment (opt-in via `AGENTBYTE_OTEL_CAPTURE_USAGE=true`):
	- `gen_ai.agent.finish_reason`
	- `gen_ai.agent.llm_calls`
	- `gen_ai.usage.duration_ms`
	- `gen_ai.usage.input_tokens`
	- `gen_ai.usage.output_tokens`
	- `gen_ai.usage.total_tokens`
	- `gen_ai.usage.cost_estimate_usd`

### Changed
- OTel examples now set `AGENTBYTE_OTEL_CAPTURE_USAGE=true` to demonstrate final task-level usage aggregation on root spans.
- OTel middleware now uses `Usage.total_tokens` directly for span attribute emission.

### Documentation
- Updated README to position Agentbyte as an observability-first agentic AI framework.
- Added no-UI Jaeger debugging workflow (API-based trace inspection with `curl`).

## [0.2.5] - 2026-03-02

### Changed
- Synced release documentation with code version and updated release-facing project docs.
- Updated release process guidance in repository instructions to require `README.md` and `CHANGELOG.md` updates for every tag.

### Documentation
- Updated README release section to reflect the new version and current highlights.

## [0.2.4] - 2026-03-02

### Added
- New use-case notebook: `04.2-metadata-extraction-large-doc.ipynb` for progressive chunked metadata extraction with memory and aggregation.
- New concept sample-data JSON files for ASMD/ESMD synthetic contract metadata.
- Project logo asset at `logo/agent-byte-avatar-low.png`.

### Changed
- Reorganized notebooks into `notebooks/concepts/agent/` and `notebooks/usecases/` with updated naming.
- Refreshed multiple concept notebooks for agent, middleware, memory, OTel, and agent-as-tool flows.

## [0.2.3] - 2026-03-02

### Changed
- Unified `Conversation` and `Workspace` into a single `Session` model. Both were structurally identical; domain semantics now live in `Session.metadata` (e.g. `{"name": "Blog Post"}`).
- `session.py` now contains `Session(Entity)`, `BaseSession(ABC)`, and `InMemorySession` — flat pattern mirroring `memory/base.py`.
- `AgentContext.conversation_id` field removed. `session_id: Optional[str]` (already present) is the sole context-level session link.

### Removed
- `src/agentbyte/conversation/` module and all exports (`Conversation`, `BaseConversation`, `InMemoryConversation`).
- `src/agentbyte/workspace/` module and all exports (`Workspace`, `BaseWorkspace`, `InMemoryWorkspace`).
- `tests/test_conversation.py`, `tests/test_workspace.py`, `tests/agents/test_agent_conversation_integration.py`.

### Added
- `tests/test_session.py` — 19 tests covering `Session` identity/equality, `to_context()`/`from_context()`, `InMemorySession` CRUD, copy-safety, and ABC contract.

### Reorganized
- Notebooks moved from flat layout into `notebooks/agent/`, `notebooks/auth/`, and `notebooks/usecase/` subdirectories.

## [0.2.1] - 2026-02-27

### Changed
- Updated package metadata for project URLs (Homepage, Repository, Issues, Changelog).
- Updated README installation guidance for `pip`/`uv add` extras usage.

### Added
- Added root `LICENSE` file (MIT) for distribution compliance and clarity.

## [0.2.0] - 2026-02-27

### Added
- Memory serialization parity (`ListMemoryConfig`, `FileMemoryConfig`, `_to_config`, `_from_config`).
- Agent-managed memory tooling via `MemoryTool` and `MemoryBackend`.
- Middleware-driven memory access routing (`operation="memory_access"`).
- `ApprovalMiddleware` for centralized tool-approval policy.
- OpenTelemetry middleware and auto-instrumentation support.
- Notebook examples for middleware patterns and real-client logging middleware.
- New/expanded tests for middleware, memory, package API, and OTel integration.

### Changed
- Middleware execution and event pipeline now support richer parity behavior with request/response/error fan-out semantics.
- Agent run paths now integrate improved middleware handling and instrumentation.
- Package API now exposes `Agent` at package root and supports opt-in auto-instrumentation via environment variable.

### Fixed
- Token usage mapping alignment in telemetry paths (`tokens_input`, `tokens_output`).
- Auto-instrumentation idempotency for repeated setup calls.

## [0.1.2] - 2026-02-25

### Added
- Initial middleware and memory completion pass (streaming middleware baseline, approval pause integration, memory tooling foundations).
