agentbyte 0.30.0__tar.gz → 0.31.0__tar.gz

{agentbyte-0.30.0 → agentbyte-0.31.0}/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [Unreleased]
+
+## [0.31.0] - 2026-09-30
+
+Upgrade notes (breaking):
+
+- `ContextCompactionMiddleware(max_tokens=..., keep_last=...)` → `ContextCompactionMiddleware(max_input_tokens=...)`; read counts from `metadata["compaction"]`.
+- Middleware that rewrites a `model_call` payload must keep its keys: `context.data = {**context.data, "messages": new}`.
+- Multi-call approval batches return every approval request at once; loop over `response.approval_requests`.
+- Workflow steps must write back changed state explicitly (`context.set(...)`); in-place mutation of a value read from `WorkflowContext` no longer persists.
+
+### Added
+
+- Workflow reliability (spec 0058): optional native-async `SQLiteCheckpointStore` (new `workflow-sqlite` extra, lazily imported driver) with immutable checkpoint IDs and per-run retention; checkpoint schema v2 with staged continuation and accepted responses (v1 checkpoints still load); `CheckpointStore.load_latest(..., execution_id=...)`; multiple nested input requests per step with batch validation and partial resume (`BaseStep.resume_from_requests`, `validate_resume_responses`); `WorkflowStateIsolationError`, `WorkflowCheckpointError`, `CheckpointConflictError`.
+- Context compaction (spec 0049): new `agentbyte.compaction` package with `HeadTailCompaction`, `SlidingWindowCompaction`, `CharacterTokenCounter`, optional `TiktokenCounter` and `CompactionResult`. Tool-call batches and their results are kept or removed whole; system messages and the current turn are always kept; the budget covers messages, tools and output schema. Mandatory content that cannot fit raises `ContextBudgetExceeded` before any provider call.
+- `BaseMiddleware.finalize_request` and `validate_request` hooks: after every `process_request`, the chain runs all `finalize_request` hooks (may change the payload), then all read-only `validate_request` hooks, immediately before the operation. A validator that changes the payload raises `MiddlewareContractError`.
+- Tool message metadata (spec 0056): `ToolMessage.metadata` keeps an independent copy of the final `ToolResult.metadata` (e.g. `AgentAsTool` child usage) across run, streaming, approval resume and failed results. Sessions and checkpoints preserve it; model-provider requests never include it. Records without the field load as `{}`.
+
+### Changed
+
+- **Breaking:** the agent no longer falls back to its own messages, tools or output format when middleware removes those keys from a `model_call` payload; a missing key raises. Set a key to `None` to omit it.
+- Passing a new task while the conversation ends with an unresolved tool-call batch now ends the run with `finish_reason="error"` instead of sending an invalid history; resume with `task=None` first.
+- **Breaking:** `ContextCompactionMiddleware` now takes keyword-only `max_input_tokens` (required), `strategy` and `counter`; `max_tokens` and `keep_last` were removed without aliases, and the fabricated summary placeholder is gone. Malformed, orphan or unresolved tool exchanges now raise `ToolExchangeError`/`PendingToolExchangeError` instead of being sent. Metadata moved to `metadata["compaction"]`, with per-pass counts in `passes`.
+- **Breaking:** `ToolResult.metadata` and `ToolMessage.metadata` accept JSON values only (string-keyed objects, lists, strings, finite numbers, booleans, null). Tuples, enums, non-string keys, `Path`, `datetime`, models, NaN/inf raise `ToolMetadataError` (a `TypeError`); a custom tool producing such metadata now fails its call instead of succeeding.
+- Tool metadata is now present on every `ToolMessage` sent by the WebUI server and stored in sessions, not only in verbose tool-response events.
+- `CalculatorTool` no longer duplicates the computed value in metadata, so non-finite and complex results still succeed.
+- **Breaking:** workflow staged state is isolated: `WorkflowContext` reads return detached copies, so steps must write changes back explicitly; values that cannot be isolated raise `WorkflowStateIsolationError`. Checkpoints are taken at quiescent recovery boundaries, and persistence failures stop the run with `WorkflowCheckpointError` instead of continuing unsaved.
+- `FileCheckpointStore` is deprecated (legacy blocking backend); use `SQLiteCheckpointStore` or an application durable store. Migration guidance is in the workflow skill and checkpoint study topic. FastAPI still persists through its session store.
+
+### Documentation
+
+- Context compaction notebook (`notebooks/concepts/agent/10-context-compaction.ipynb`) and FastAPI example (`examples/compaction/`) showing budgets, 413/409 mapping, turn rollback, SSE and a context meter.
+- Proposed spec 0059 (summarizing compaction).
+
+### Fixed
+
+- Multi-call tool batches stay complete across approval pauses: calls after the first approval-gated call are no longer skipped (previously the model received tool calls without results after resume). All gated calls in a batch request approval in one round; resume runs the rest in original order; missing decisions keep `approval_needed` without a model call.
+- Cancelling mid-batch records a failed `ToolMessage` (`error="Cancelled"`) for each call that did not run, so the session stays valid for the next task.
+
+## [0.30.1] - 2026-09-30
+
+### Fixed
+
+- Judge score integrity follow-ups (spec 0055 v0.3.0): judges re-check cancellation after each model call, and `EvalRunner`/`PairwiseRunner` record a run as `cancelled` without judging it when the token is cancelled or the trajectory has `execution_status="cancelled"`.
+- Raw-JSON judge responses with duplicate keys are rejected (`duplicate_criterion` for `LLMEvalJudge`, `invalid_response` for `PairwiseJudge`) instead of keeping the last value.
+- When a target raises, `EvalRunner` and `PairwiseRunner` store only the exception type in `trajectory.error`, never the exception message.
+- `ModelEvalTarget` records `execution_status` on failed and cancelled trajectories.
+
+### Changed
+
+- **Breaking:** `criteria=None` selects judge defaults; an explicit empty list raises `JudgeScoringError("invalid_criteria")`. An empty `default_criteria` (`LLMEvalJudge`, `LLMTrajectoryJudge`) or `criteria` (`PairwiseJudge`) raises `ValueError` at construction.
+- **Breaking:** a scored `EvalScore` carrying legacy `fallback` or `judge_failed` metadata fails validation.
+
 ## [0.30.0] - 2026-09-30
 
 ### Added

{agentbyte-0.30.0 → agentbyte-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.30.0
+Version: 0.31.0
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -80,13 +80,15 @@ Requires-Dist: graphviz>=0.21; extra == 'viz'
 Provides-Extra: webui
 Requires-Dist: fastapi>=0.135.2; extra == 'webui'
 Requires-Dist: uvicorn[standard]>=0.44.0; extra == 'webui'
+Provides-Extra: workflow-sqlite
+Requires-Dist: aiosqlite>=0.22.1; extra == 'workflow-sqlite'
 Description-Content-Type: text/markdown
 
 # Agentbyte
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.30.0**
+Current release: **0.31.0**
 
 ## Building an Agent
 

{agentbyte-0.30.0 → agentbyte-0.31.0}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.30.0**
+Current release: **0.31.0**
 
 ## Building an Agent
 

{agentbyte-0.30.0 → agentbyte-0.31.0}/pyproject.toml

@@ -41,6 +41,9 @@ webui = [
 dataset = [
     "aiosqlite>=0.22.1",
 ]
+workflow-sqlite = [
+    "aiosqlite>=0.22.1",
+]
 sql = [
     "sqlalchemy>=2.0.43",
     "sqlmodel>=0.0.38",

agentbyte-0.31.0/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.31.0"
+VERSION = __version__

{agentbyte-0.30.0 → agentbyte-0.31.0}/src/agentbyte/agents/agent.py

@@ -234,6 +234,7 @@ class Agent(BaseAgent):
                     tool_name=tool_call.tool_name,
                     success=streamed_result.success,
                     error=streamed_result.error,
+                    metadata=streamed_result.metadata,
                 )
                 working_context.add_message(tool_message)
                 yield tool_message
@@ -317,6 +318,7 @@ class Agent(BaseAgent):
                 tool_name=tool_call.tool_name,
                 success=result.success,
                 error=result.error,
+                metadata=result.metadata,
             )
         except Exception as exc:
             message = ToolMessage(
@@ -339,6 +341,102 @@ class Agent(BaseAgent):
 
         yield message
 
+    @staticmethod
+    def _unresolved_tail_calls(working_context: AgentContext) -> List[ToolCallRequest]:
+        """Calls of the newest tool-call batch that have no result yet, in order.
+
+        Only a batch followed exclusively by tool results counts; results are
+        matched to that batch occurrence, not to earlier reuses of a call ID.
+        """
+        resolved: set[str] = set()
+        for message in reversed(working_context.messages):
+            if isinstance(message, ToolMessage):
+                resolved.add(message.tool_call_id)
+                continue
+            if isinstance(message, AssistantMessage) and message.tool_calls:
+                return [c for c in message.tool_calls if c.call_id not in resolved]
+            return []
+        return []
+
+    def _awaits_approval(
+        self,
+        tool_call: ToolCallRequest,
+        working_context: AgentContext,
+        extra_tools: Optional[List[BaseTool]],
+    ) -> bool:
+        """Whether *tool_call* needs an approval decision that does not exist yet."""
+        tool = self._find_tool(tool_call.tool_name, extra_tools=extra_tools)
+        return (
+            tool is not None
+            and tool.approval_mode == ApprovalMode.ALWAYS
+            and working_context.get_approval_response(tool_call.call_id) is None
+        )
+
+    async def _resolve_tool_batch(
+        self,
+        working_context: AgentContext,
+        cancellation_token: Optional[CancellationToken],
+        verbose: bool,
+        extra_tools: Optional[List[BaseTool]],
+        outcome: dict[str, int | bool],
+    ) -> AsyncGenerator[Union[Message, AgentEvent], None]:
+        """Execute the newest batch's unresolved calls in their original order.
+
+        Execution stops before the first call still awaiting approval; approval
+        requests for every such call in the batch are registered together, so a
+        single decision round resolves the batch. Calls left unexecuted because
+        of cancellation receive an explicit failed result, keeping the batch
+        complete. ``outcome`` reports ``executed`` and ``paused``.
+        """
+        pending = self._unresolved_tail_calls(working_context)
+        awaiting = [
+            c for c in pending if self._awaits_approval(c, working_context, extra_tools)
+        ]
+        stop_at = awaiting[0].call_id if awaiting else None
+
+        for tool_call in pending:
+            if tool_call.call_id == stop_at:
+                break
+            outcome["executed"] = int(outcome["executed"]) + 1
+            try:
+                async for item in self._execute_tool_call(
+                    tool_call,
+                    working_context,
+                    cancellation_token,
+                    verbose,
+                    extra_tools=extra_tools,
+                ):
+                    yield item
+                    if isinstance(item, ToolApprovalEvent):
+                        outcome["paused"] = True
+                        return
+            except asyncio.CancelledError:
+                for skipped in self._unresolved_tail_calls(working_context):
+                    working_context.add_message(
+                        ToolMessage(
+                            content="Tool execution cancelled before it ran",
+                            source=self.name,
+                            tool_call_id=skipped.call_id,
+                            tool_name=skipped.tool_name,
+                            success=False,
+                            error="Cancelled",
+                        )
+                    )
+                raise
+
+        if not awaiting:
+            return
+
+        outcome["paused"] = True
+        for tool_call in awaiting:
+            if tool_call.call_id in working_context.pending_tool_calls:
+                continue  # already requested in an earlier run
+            request = working_context.add_approval_request(
+                tool_call=tool_call,
+                tool_name=tool_call.tool_name,
+            )
+            yield ToolApprovalEvent(source=self.name, approval_request=request)
+
     @trace_stream("agent")
     async def run_stream(
         self,
@@ -428,6 +526,11 @@ class Agent(BaseAgent):
 
         try:
             task_messages = self._convert_task_to_messages(task) if task else []
+            if task_messages and self._unresolved_tail_calls(working_context):
+                raise AgentExecutionError(
+                    "The conversation ends with unresolved tool calls; resolve pending "
+                    "approvals by resuming with task=None before sending a new task."
+                )
             for message in task_messages:
                 working_context.add_message(message)
 
@@ -453,32 +556,22 @@ class Agent(BaseAgent):
                 if cancellation_token and cancellation_token.is_cancelled():
                     raise asyncio.CancelledError()
 
-                approved_calls = working_context.get_approved_tool_calls()
-                rejected_calls = working_context.get_rejected_tool_calls()
-
-                for approved_call in approved_calls:
-                    tool_calls += 1
-                    async for item in self._execute_tool_call(
-                        approved_call,
+                # Resume: finish the newest tool-call batch (approved, denied and
+                # not-yet-run siblings, in order) before asking the model again.
+                if self._unresolved_tail_calls(working_context):
+                    outcome: dict[str, int | bool] = {"executed": 0, "paused": False}
+                    async for item in self._resolve_tool_batch(
                         working_context,
                         cancellation_token,
                         verbose,
-                        skip_approval_check=True,
-                        extra_tools=provider_tools,
+                        provider_tools,
+                        outcome,
                     ):
                         yield item
-
-                for rejected_call_id, rejected_call in rejected_calls:
-                    denial_message = ToolMessage(
-                        content="Tool execution denied: User declined approval",
-                        source=self.name,
-                        tool_call_id=rejected_call_id,
-                        tool_name=rejected_call.tool_name,
-                        success=False,
-                        error="Approval denied",
-                    )
-                    working_context.add_message(denial_message)
-                    yield denial_message
+                    tool_calls += int(outcome["executed"])
+                    if outcome["paused"]:
+                        finish_reason = "approval_needed"
+                        break
 
                 llm_messages = await self._prepare_llm_messages([], working_context, extra_instructions=extra_instructions)
                 if self.memory is not None:
@@ -560,11 +653,25 @@ class Agent(BaseAgent):
                     break
 
                 async def _execute_model_call(payload: dict[str, object]):
-                    payload_messages = payload.get("messages", llm_messages)
+                    # Send exactly the final middleware payload: falling back to
+                    # the agent's own values would bypass request validation
+                    # (e.g. compaction budgets) done on that payload.
+                    missing = [
+                        key
+                        for key in ("messages", "tools", "output_format")
+                        if key not in payload
+                    ]
+                    if missing:
+                        raise ValueError(
+                            f"model_call payload is missing {missing}; middleware "
+                            "must preserve payload keys (set a key to None to omit it)"
+                        )
+
+                    payload_messages = payload["messages"]
                     if not isinstance(payload_messages, list):
                         raise ValueError("model_call payload messages must be a list")
 
-                    payload_tools = payload.get("tools", tools)
+                    payload_tools = payload["tools"]
                     if payload_tools is not None and not isinstance(
                         payload_tools, list
                     ):
@@ -572,9 +679,7 @@ class Agent(BaseAgent):
                             "model_call payload tools must be a list or None"
                         )
 
-                    payload_output_format = payload.get(
-                        "output_format", self.output_format
-                    )
+                    payload_output_format = payload["output_format"]
                     if payload_output_format is not None and not isinstance(
                         payload_output_format, type
                     ):
@@ -667,27 +772,18 @@ class Agent(BaseAgent):
                         finish_reason = "max_iterations_finalized"
                     break
 
-                approval_pause = False
-                for tool_call in assistant_message.tool_calls:
-                    tool_calls += 1
-                    async for item in self._execute_tool_call(
-                        tool_call,
-                        working_context,
-                        cancellation_token,
-                        verbose,
-                        extra_tools=provider_tools,
-                    ):
-                        yield item
-
-                        if isinstance(item, ToolApprovalEvent):
-                            finish_reason = "approval_needed"
-                            approval_pause = True
-                            break
-
-                    if approval_pause:
-                        break
-
-                if approval_pause:
+                outcome = {"executed": 0, "paused": False}
+                async for item in self._resolve_tool_batch(
+                    working_context,
+                    cancellation_token,
+                    verbose,
+                    provider_tools,
+                    outcome,
+                ):
+                    yield item
+                tool_calls += int(outcome["executed"])
+                if outcome["paused"]:
+                    finish_reason = "approval_needed"
                     break
 
                 if not self.summarize_tool_result:

agentbyte-0.31.0/src/agentbyte/compaction/__init__.py

@@ -0,0 +1,41 @@
+"""Context compaction that keeps outbound conversations provider-valid.
+
+Strategies select whole message groups (a tool request and all its results are
+one group) so that a complete model-call request fits an input-token budget,
+or raise :class:`ContextBudgetExceeded` before any provider I/O.
+"""
+
+from agentbyte.compaction.counters import (
+    CharacterTokenCounter,
+    TiktokenCounter,
+    TokenCounter,
+)
+from agentbyte.compaction.errors import (
+    CompactionError,
+    ContextBudgetExceeded,
+    PendingToolExchangeError,
+    ToolExchangeError,
+)
+from agentbyte.compaction.grouping import MessageGroup, group_messages
+from agentbyte.compaction.strategies import (
+    CompactionResult,
+    CompactionStrategy,
+    HeadTailCompaction,
+    SlidingWindowCompaction,
+)
+
+__all__ = [
+    "CharacterTokenCounter",
+    "CompactionError",
+    "CompactionResult",
+    "CompactionStrategy",
+    "ContextBudgetExceeded",
+    "HeadTailCompaction",
+    "MessageGroup",
+    "PendingToolExchangeError",
+    "SlidingWindowCompaction",
+    "TiktokenCounter",
+    "TokenCounter",
+    "ToolExchangeError",
+    "group_messages",
+]

agentbyte-0.31.0/src/agentbyte/compaction/counters.py

@@ -0,0 +1,192 @@
+"""Token counters used to budget complete model-call requests.
+
+Counts are estimates: they approximate, but never promise, provider-exact
+token usage. Text is counted as text (Unicode code points / tokenizer tokens),
+never as escaped JSON sequences, and internal metadata that is not sent to
+providers (for example ``ToolMessage.metadata``) is excluded.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel
+
+from agentbyte.messages import (
+    AssistantMessage,
+    MultiModalMessage,
+    SystemMessage,
+    ToolMessage,
+    UserMessage,
+)
+
+_KNOWN_MESSAGE_TYPES = (
+    SystemMessage,
+    UserMessage,
+    AssistantMessage,
+    ToolMessage,
+    MultiModalMessage,
+)
+
+
+def _to_json_text(value: Any) -> str:
+    """Serialize *value* compactly without escaping non-ASCII characters."""
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, default=str)
+
+
+class TokenCounter(ABC):
+    """Counts tokens for every component of a model-call request.
+
+    Subclasses implement :meth:`count_text`; message, tool and schema counting
+    is shared so that every counter budgets the same request components.
+    """
+
+    #: Label recorded in results and metadata (e.g. ``"character_estimate"``).
+    kind: str = "custom"
+
+    def __init__(self, *, message_overhead: int = 4, media_tokens: int = 1_000):
+        if message_overhead < 0:
+            raise ValueError("message_overhead must be non-negative")
+        if media_tokens < 0:
+            raise ValueError("media_tokens must be non-negative")
+        self.message_overhead = message_overhead
+        self.media_tokens = media_tokens
+
+    @abstractmethod
+    def count_text(self, text: str) -> int:
+        """Return the token count for plain *text*."""
+
+    def count_message(self, message: Any) -> int:
+        """Count one outbound message, including tool-call arguments and media.
+
+        Messages of unknown types are never interpreted: their whole serialized
+        form is counted, so the budget errs towards overcounting.
+        """
+        if not isinstance(message, _KNOWN_MESSAGE_TYPES):
+            opaque = (
+                message.model_dump_json()
+                if isinstance(message, BaseModel)
+                else str(message)
+            )
+            return self.message_overhead + self.count_text(opaque)
+
+        tokens = self.message_overhead
+        content = getattr(message, "content", None)
+        if isinstance(content, str):
+            tokens += self.count_text(content)
+        elif content is not None:
+            tokens += self.count_text(_to_json_text(content))
+
+        if isinstance(message, AssistantMessage) and message.tool_calls:
+            for call in message.tool_calls:
+                tokens += self.count_text(call.tool_name)
+                tokens += self.count_text(call.call_id)
+                tokens += self.count_text(_to_json_text(call.parameters))
+        elif isinstance(message, ToolMessage):
+            tokens += self.count_text(message.tool_call_id)
+        elif isinstance(message, MultiModalMessage):
+            if message.is_text() and message.data is not None:
+                data = message.data
+                text = data.decode("utf-8", errors="ignore") if isinstance(data, bytes) else data
+                if text != message.content:
+                    tokens += self.count_text(text)
+            else:
+                # Binary media is budgeted with a declared flat estimate; its
+                # base64 payload is not text and is never counted as such.
+                tokens += self.media_tokens
+        return tokens
+
+    def count_messages(self, messages: list[Any]) -> int:
+        """Count a list of outbound messages."""
+        return sum(self.count_message(message) for message in messages)
+
+    def count_tools(self, tools: list[dict[str, Any]] | None) -> int:
+        """Count provider tool definitions."""
+        if not tools:
+            return 0
+        return sum(self.count_text(_to_json_text(tool)) for tool in tools)
+
+    def count_output_schema(self, output_schema: Any) -> int:
+        """Count a structured-output schema (Pydantic model type or JSON schema)."""
+        if output_schema is None:
+            return 0
+        if isinstance(output_schema, type) and issubclass(output_schema, BaseModel):
+            return self.count_text(_to_json_text(output_schema.model_json_schema()))
+        return self.count_text(_to_json_text(output_schema))
+
+    def count_request(
+        self,
+        messages: list[Any],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        output_schema: Any = None,
+    ) -> int:
+        """Count the complete request input: messages, tools and output schema."""
+        return (
+            self.count_messages(messages)
+            + self.count_tools(tools)
+            + self.count_output_schema(output_schema)
+        )
+
+
+class CharacterTokenCounter(TokenCounter):
+    """Dependency-free estimate: Unicode characters divided by ``chars_per_token``.
+
+    Rounds up per text component, so any nonempty text costs at least one token.
+    Accuracy varies by language and tokenizer; treat counts as estimates.
+    """
+
+    kind = "character_estimate"
+
+    def __init__(
+        self,
+        *,
+        chars_per_token: float = 4.0,
+        message_overhead: int = 4,
+        media_tokens: int = 1_000,
+    ):
+        super().__init__(message_overhead=message_overhead, media_tokens=media_tokens)
+        if chars_per_token <= 0:
+            raise ValueError("chars_per_token must be greater than zero")
+        self.chars_per_token = chars_per_token
+
+    def count_text(self, text: str) -> int:
+        if not text:
+            return 0
+        return math.ceil(len(text) / self.chars_per_token)
+
+
+class TiktokenCounter(TokenCounter):
+    """Estimate using a ``tiktoken`` encoding (optional dependency).
+
+    Tokenizer counts are closer to OpenAI-family billing but still exclude
+    provider-specific framing, so they remain estimates.
+    """
+
+    kind = "tiktoken_estimate"
+
+    def __init__(
+        self,
+        encoding_name: str = "o200k_base",
+        *,
+        message_overhead: int = 4,
+        media_tokens: int = 1_000,
+    ):
+        super().__init__(message_overhead=message_overhead, media_tokens=media_tokens)
+        try:
+            import tiktoken
+        except ImportError as exc:
+            raise ImportError(
+                "TiktokenCounter requires the optional 'tiktoken' package; "
+                "install it or use CharacterTokenCounter."
+            ) from exc
+        self.encoding_name = encoding_name
+        self._encoding = tiktoken.get_encoding(encoding_name)
+
+    def count_text(self, text: str) -> int:
+        if not text:
+            return 0
+        return len(self._encoding.encode(text, disallowed_special=()))

agentbyte-0.31.0/src/agentbyte/compaction/errors.py

@@ -0,0 +1,44 @@
+"""Exceptions raised by context compaction."""
+
+from __future__ import annotations
+
+
+class CompactionError(Exception):
+    """Base class for context-compaction failures."""
+
+
+class ToolExchangeError(CompactionError):
+    """Outbound history contains a malformed or orphaned tool exchange.
+
+    Raised before provider I/O. Compaction never repairs history by inventing
+    tool calls or results.
+    """
+
+
+class PendingToolExchangeError(ToolExchangeError):
+    """A tool-call batch has no result for one or more calls.
+
+    The unresolved batch stays in session history, but it cannot be sent for a
+    new model generation until every call has a result or approval resolution.
+    """
+
+    def __init__(self, message: str, *, pending_call_ids: list[str]):
+        super().__init__(message)
+        self.pending_call_ids = pending_call_ids
+
+
+class ContextBudgetExceeded(CompactionError):
+    """Mandatory request content cannot fit the configured input budget."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        required_tokens: int,
+        max_input_tokens: int,
+        counter_kind: str,
+    ):
+        super().__init__(message)
+        self.required_tokens = required_tokens
+        self.max_input_tokens = max_input_tokens
+        self.counter_kind = counter_kind