agent-framework-core 1.16.0__tar.gz → 1.17.0__tar.gz

{agent_framework_core-1.16.0 → agent_framework_core-1.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-core
-Version: 1.16.0
+Version: 1.17.0
 Summary: Microsoft Agent Framework for building AI Agents with Python. This is the core package that has all the core abstractions and implementations.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.10
@@ -21,7 +21,6 @@ Requires-Dist: typing-extensions>=4.15.0,<5
 Requires-Dist: pydantic>=2,<3
 Requires-Dist: python-dotenv>=1,<2
 Requires-Dist: opentelemetry-api>=1.39.0,<2
-Requires-Dist: agent-hooks-sdk>=0.1.0a4,<0.2 ; extra == "agent-hooks"
 Requires-Dist: mcp>=1.24.0,<2 ; extra == "all"
 Requires-Dist: agent-framework-a2a ; extra == "all"
 Requires-Dist: agent-framework-ag-ui ; extra == "all"
@@ -57,7 +56,6 @@ Project-URL: homepage, https://aka.ms/agent-framework
 Project-URL: issues, https://github.com/microsoft/agent-framework/issues
 Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
 Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
-Provides-Extra: agent-hooks
 Provides-Extra: all
 
 # Get Started with Microsoft Agent Framework

{agent_framework_core-1.16.0 → agent_framework_core-1.17.0}/agent_framework/_agent_hooks.py

@@ -93,7 +93,7 @@ per-run points and the host owns the session boundaries.
 
 The ``agent-hooks-sdk`` dependency is optional: importing this module (and the lazy root
 exports) works without it, and the factories raise a descriptive ``ModuleNotFoundError``
-when the SDK is missing. Install it via ``pip install agent-framework-core[agent-hooks]``.
+when the SDK is missing. Install it via ``pip install agent-hooks-sdk``.
 """
 
 from __future__ import annotations
@@ -162,7 +162,7 @@ _DEFAULT_TIMEOUT = 5.0
 
 _SDK_MISSING_MESSAGE = (
     "The agent-hooks middleware requires the optional `agent-hooks-sdk` package. "
-    "Please install `agent-framework-core[agent-hooks]` (or `agent-hooks-sdk`)."
+    "Please install it with `pip install agent-hooks-sdk`."
 )
 
 _TRIO_REQUIRED_MESSAGE = (
@@ -191,7 +191,7 @@ def _require_sdk() -> None:
     """Import the SDK surface this module uses at runtime, with a helpful install hint.
 
     Only a genuinely missing ``agent_hooks`` package is translated into the
-    install-the-extra message; anything else (a broken installation, an incompatible
+    SDK installation message; anything else (a broken installation, an incompatible
     SDK version missing symbols, a failing transitive import) propagates unchanged so
     real breakage is not masked as a missing extra.
     """
@@ -862,23 +862,99 @@ def _agent_updates_from_response(response: AgentResponse[Any]) -> list[AgentResp
     return updates
 
 
-def _tool_names(context: AgentContext) -> list[str]:
-    """Project the registered tool names for ``agent_startup`` (spec ``tools_registered``)."""
-    from ._tools import _get_tool_name, normalize_tools  # type: ignore[reportPrivateUsage]
+def _normalized_tools(tools: Any, *, point: str) -> list[Any]:
+    """Normalize a tools value for projection; empty (with a warning) when it cannot be.
+
+    Everything — including the emptiness check inside ``normalize_tools`` — runs under
+    the guard, so a tools container whose ``__bool__``/``__len__``/``__iter__`` raises
+    degrades to omitting the projection instead of aborting the emission mid-run.
+    """
+    from ._tools import normalize_tools
 
-    tools: Any = context.tools if context.tools is not None else getattr(context.agent, "tools", None)
-    if tools is None:
+    try:
+        return list(normalize_tools(tools))
+    except Exception:
+        logger.warning("agent-hooks could not normalize the tools for the %s projection.", point)
         return []
+
+
+def _projected_tool_name(item: Any) -> str:
+    """Project a tool's display name; hosted-tool mappings fall back to their ``type``."""
+    from ._tools import _get_tool_name  # type: ignore[reportPrivateUsage]
+
+    fallback = type(item).__name__
+    name = _get_tool_name(item)
+    if name:
+        return name
+    if isinstance(item, Mapping):
+        # Hosted-tool mappings carry top-level fields (no nested "function"), e.g.
+        # {"type": "web_search"} or {"type": "web_search_20250305", "name": "web_search"}.
+        mapping = cast("Mapping[str, Any]", item)
+        for key in ("name", "type"):
+            value = mapping.get(key)
+            if isinstance(value, str) and value:
+                return value
+    return fallback
+
+
+def _tool_description(item: Any) -> str | None:
+    """Extract a tool description from a tool object or dict tool definition."""
+    if isinstance(item, Mapping):
+        mapping = cast("Mapping[str, Any]", item)
+        function = mapping.get("function")
+        # Function-tool dicts nest the description; hosted-tool mappings keep it top-level.
+        description = (
+            cast("Mapping[str, Any]", function).get("description")
+            if isinstance(function, Mapping)
+            else mapping.get("description")
+        )
+        return description if isinstance(description, str) else None
+    description = getattr(item, "description", None)
+    return description if isinstance(description, str) else None
+
+
+def _tool_names(context: AgentContext) -> list[str]:
+    """Project the run-start tool names for ``agent_startup`` (spec ``tools_registered``).
+
+    The framework owns the run-start resolution — ``AgentContext._resolve_run_start_tools``
+    returns the agent-declared tools plus this invocation's run-level tools (the named
+    ``tools`` parameter takes precedence over a ``tools`` entry in the options mapping),
+    already normalized — so this helper is projection only. This is deliberately the
+    run-start snapshot: tools registered dynamically during the run (for example by
+    context providers during run preparation, or by MCP servers whose functions expand
+    at connect time) cannot be known at ``agent_startup`` time; they surface in each
+    ``pre_model_call`` emission's ``tools`` projection (the completed per-call set) and
+    are bracketed by ``pre_tool_call``/``post_tool_call`` like any other tool when
+    invoked. An unresolvable set degrades to a warning and an empty snapshot rather
+    than aborting the emission.
+    """
     try:
-        normalized = normalize_tools(tools)
+        resolved = context._resolve_run_start_tools()  # pyright: ignore[reportPrivateUsage]
     except Exception:
-        logger.warning("agent-hooks could not normalize the run's tools for the agent_startup projection.")
+        logger.warning("agent-hooks could not resolve the run-start tools for the agent_startup projection.")
         return []
-    names: list[str] = []
-    for item in normalized:
-        name = _get_tool_name(item)
-        names.append(name if name else type(item).__name__)
-    return names
+    return [_projected_tool_name(item) for item in resolved]
+
+
+def _pre_model_call_tools(options: Mapping[str, Any]) -> list[dict[str, Any]] | None:
+    """Project the per-call effective tool set for ``pre_model_call`` (spec ``tools``).
+
+    This is the completed set for this model call — the run-start tools plus anything
+    registered during the run (context-provider tools, connected MCP-server functions,
+    progressive tool exposure) — whereas ``agent_startup``'s ``tools_registered`` is the
+    run-start snapshot. Entries carry ``{"name", "description"?}`` (description omitted
+    when the tool has none). Returns ``None`` — the spec's optional field is omitted —
+    when the call offers no tools or the set cannot be projected, so an unprojectable
+    set is never misreported as "no tools".
+    """
+    projected: list[dict[str, Any]] = []
+    for item in _normalized_tools(options.get("tools"), point="pre_model_call"):
+        entry: dict[str, Any] = {"name": _projected_tool_name(item)}
+        description = _tool_description(item)
+        if description:
+            entry["description"] = description
+        projected.append(entry)
+    return projected or None
 
 
 def _is_host_error(record: InterceptionRecord) -> bool:
@@ -1269,7 +1345,7 @@ class _AgentHooksChatMiddleware(_AgentHooksMiddlewareBase, ChatMiddleware):
         model_id = str(options.get("model") or type(context.client).__name__)
         before = _ModelRequestCodec.to_wire(context.messages)
         outcome: EmitOutcome = await state.emitter.emit(
-            state.builder.pre_model_call(model_id=model_id, messages=before)
+            state.builder.pre_model_call(model_id=model_id, messages=before, tools=_pre_model_call_tools(options))
         )
         transformed_messages = _ModelRequestCodec.write_back(context.messages, before, outcome.target)
         if transformed_messages is not None:

{agent_framework_core-1.16.0 → agent_framework_core-1.17.0}/agent_framework/_agents.py

@@ -31,6 +31,8 @@ from ._middleware import (
     FunctionInvocationContext,
     MiddlewareTypes,
     _as_middleware_list,  # pyright: ignore[reportPrivateUsage]
+    _copy_middleware_sequence,  # pyright: ignore[reportPrivateUsage]
+    _select_run_level_tools,  # pyright: ignore[reportPrivateUsage]
     categorize_middleware,
 )
 from ._serialization import SerializationMixin
@@ -439,7 +441,7 @@ class BaseAgent(SerializationMixin):
         name: str | None = None,
         description: str | None = None,
         context_providers: Sequence[ContextProvider] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         additional_properties: MutableMapping[str, Any] | None = None,
     ) -> None:
         """Initialize a BaseAgent instance.
@@ -450,10 +452,8 @@ class BaseAgent(SerializationMixin):
             name: The name of the agent, can be None.
             description: The description of the agent.
             context_providers: Context providers to include during agent invocation.
-            middleware: List of middleware, or a single middleware object (including a
-                ``MiddlewareBundle``) which is treated as a one-element list. The
-                constructor copies the sequence; assign to or mutate the
-                ``middleware`` attribute for post-construction changes.
+            middleware: List of middleware. The constructor copies the sequence; assign
+                to or mutate the ``middleware`` attribute for post-construction changes.
             additional_properties: Additional properties set on the agent.
         """
         if id is None:
@@ -462,11 +462,8 @@ class BaseAgent(SerializationMixin):
         self.name = name
         self.description = description
         self.context_providers: list[ContextProvider] = list(context_providers or [])
-        # Canonicalize storage: the bare-source rule (a single middleware object or a
-        # MiddlewareBundle is one element) is owned by _as_middleware_list; storing a
-        # normalized list keeps the declared attribute type honest.
         self.middleware: list[MiddlewareTypes] | None = (
-            _as_middleware_list(middleware) if middleware is not None else None
+            _copy_middleware_sequence(middleware) if middleware is not None else None
         )
         self.additional_properties: dict[str, Any] = cast(dict[str, Any], additional_properties or {})
 
@@ -819,7 +816,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         context_providers: Sequence[ContextProvider] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         require_per_service_call_history_persistence: bool = False,
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,
@@ -838,8 +835,6 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
             description: A brief description of the agent's purpose.
             context_providers: Context providers to include during agent invocation.
             middleware: List of middleware to intercept agent and function invocations.
-                A single middleware object (including a ``MiddlewareBundle``) is
-                treated as a one-element list.
             require_per_service_call_history_persistence: When True (and a HistoryProvider is
                 present), the provider always persists history via per-service-call middleware,
                 regardless of whether the client stores history server-side. If the client does
@@ -1365,8 +1360,13 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         opts = dict(options) if options else {}
         existing_additional_args: dict[str, Any] = opts.pop("additional_function_arguments", None) or {}
 
-        # Get tools from options or named parameter (named param takes precedence)
-        tools_ = tools if tools is not None else opts.pop("tools", None)
+        # Run-level tools: the named parameter takes precedence over an options entry
+        # (_select_run_level_tools is the framework's single statement of that rule,
+        # shared with the middleware layer's run-start resolution). The options entry
+        # is consumed either way, so a losing options["tools"] can never ride the
+        # remaining options into the request and silently override the resolved list.
+        tools_ = _select_run_level_tools(tools, opts)
+        opts.pop("tools", None)
 
         input_messages = normalize_messages(messages)
 
@@ -1808,7 +1808,7 @@ class Agent(
         *,
         stream: Literal[False] = ...,
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: ChatOptions[ResponseModelBoundT],
         compaction_strategy: CompactionStrategy | None = None,
@@ -1824,7 +1824,7 @@ class Agent(
         *,
         stream: Literal[False] = ...,
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: OptionsCoT | ChatOptions[None] | None = None,
         compaction_strategy: CompactionStrategy | None = None,
@@ -1840,7 +1840,7 @@ class Agent(
         *,
         stream: Literal[True],
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: OptionsCoT | ChatOptions[Any] | None = None,
         compaction_strategy: CompactionStrategy | None = None,
@@ -1855,7 +1855,7 @@ class Agent(
         *,
         stream: bool = False,
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: OptionsCoT | ChatOptions[Any] | None = None,
         compaction_strategy: CompactionStrategy | None = None,
@@ -1893,7 +1893,7 @@ class Agent(
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         context_providers: Sequence[ContextProvider] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         require_per_service_call_history_persistence: bool = False,
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,

{agent_framework_core-1.16.0 → agent_framework_core-1.17.0}/agent_framework/_clients.py

@@ -96,6 +96,10 @@ class SupportsChatGetResponse(Protocol[OptionsContraT]):
         Protocols use structural subtyping (duck typing). Classes don't need
         to explicitly inherit from this protocol to be considered compatible.
 
+        Implementing this protocol does not by itself guarantee that an instance
+        can be reused across concurrent calls. Check the concrete client's
+        concurrency contract before sharing it.
+
     Examples:
         .. code-block:: python
 
@@ -578,7 +582,7 @@ class BaseChatClient(SerializationMixin, ABC, Generic[OptionsCoT]):
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | Mapping[str, Any] | None = None,
         context_providers: Sequence[Any] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         require_per_service_call_history_persistence: bool = False,
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,

{agent_framework_core-1.16.0 → agent_framework_core-1.17.0}/agent_framework/_compaction.py

@@ -375,6 +375,76 @@ def _set_group_summarized_by_summary_id(message: Message, summary_id: str) -> No
     annotation[SUMMARIZED_BY_SUMMARY_ID_KEY] = summary_id
 
 
+def _reconcile_compaction_summaries(  # pyright: ignore[reportUnusedFunction]
+    source_messages: list[Message],
+    working_messages: Sequence[Message],
+    previous_message_ids: set[int],
+) -> None:
+    """Reconcile summaries of source messages without persisting unrelated rewrites."""
+    source_message_ids = {message.message_id for message in source_messages if message.message_id}
+    candidates: list[tuple[Message, set[str]]] = []
+    for message in working_messages:
+        if id(message) in previous_message_ids:
+            continue
+
+        annotation = _read_group_annotation_raw(message)
+        if annotation is None:
+            continue
+        summarized_message_ids: Any = annotation.get(SUMMARY_OF_MESSAGE_IDS_KEY)
+        if (
+            message.message_id
+            and isinstance(summarized_message_ids, list)
+            and summarized_message_ids
+            and all(isinstance(value, str) for value in cast("list[Any]", summarized_message_ids))
+        ):
+            candidates.append((message, set(cast("list[str]", summarized_message_ids))))
+
+    dependencies = {message.message_id: summary_ids for message, summary_ids in candidates if message.message_id}
+    supported_ids = set(source_message_ids)
+    pending_ids = set(dependencies)
+    while pending_ids:
+        newly_supported = {summary_id for summary_id in pending_ids if dependencies[summary_id].issubset(supported_ids)}
+        if not newly_supported:
+            break
+        supported_ids.update(newly_supported)
+        pending_ids.difference_update(newly_supported)
+
+    accepted_ids = set(dependencies).difference(pending_ids)
+    for message in [*source_messages, *(candidate for candidate, _ in candidates)]:
+        annotation = _read_group_annotation_raw(message)
+        if annotation is None:
+            continue
+        summary_id = annotation.get(SUMMARIZED_BY_SUMMARY_ID_KEY)
+        if not isinstance(summary_id, str) or summary_id in accepted_ids or summary_id in source_message_ids:
+            continue
+        annotation.pop(SUMMARIZED_BY_SUMMARY_ID_KEY, None)
+        message.additional_properties.pop(EXCLUDED_KEY, None)
+        message.additional_properties.pop(EXCLUDE_REASON_KEY, None)
+
+    def source_dependencies(summary_id: str) -> set[str]:
+        expanded: set[str] = set()
+        for dependency_id in dependencies[summary_id]:
+            if dependency_id in source_message_ids:
+                expanded.add(dependency_id)
+            elif dependency_id in accepted_ids:
+                expanded.update(source_dependencies(dependency_id))
+        return expanded
+
+    for message, _ in candidates:
+        if message.message_id not in accepted_ids:
+            continue
+        summarized_source_ids = source_dependencies(message.message_id)
+        insertion_index = min(
+            (
+                index
+                for index, source_message in enumerate(source_messages)
+                if source_message.message_id in summarized_source_ids
+            ),
+            default=len(source_messages),
+        )
+        source_messages.insert(insertion_index, message)
+
+
 def _write_group_annotation(
     message: Message,
     *,
@@ -802,8 +872,8 @@ class TruncationStrategy:
     - token count when ``tokenizer`` is provided
     - included message count when ``tokenizer`` is not provided
     Compaction triggers when the metric exceeds ``max_n`` and trims toward
-    ``compact_to``. The minimum retained group is never excluded, so the
-    result may remain above ``compact_to`` when that group alone exceeds it.
+    ``compact_to``. Protected groups are never excluded, so the result may
+    remain above ``compact_to`` when those groups alone exceed it.
     """
 
     def __init__(
@@ -813,6 +883,7 @@ class TruncationStrategy:
         compact_to: int,
         tokenizer: TokenizerProtocol | None = None,
         preserve_system: bool = True,
+        preserve_first_user_group: bool = False,
     ) -> None:
         """Create a truncation strategy.
 
@@ -824,6 +895,8 @@ class TruncationStrategy:
             tokenizer: Optional tokenizer used for token-based truncation.
             preserve_system: When True, system groups remain included and only
                 non-system groups are eligible for exclusion.
+            preserve_first_user_group: When True, the earliest user group
+                remains included along with the minimum retained group.
         """
         if max_n <= 0:
             raise ValueError("max_n must be greater than 0.")
@@ -835,6 +908,7 @@ class TruncationStrategy:
         self.compact_to = compact_to
         self.tokenizer = tokenizer
         self.preserve_system = preserve_system
+        self.preserve_first_user_group = preserve_first_user_group
 
     async def __call__(self, messages: list[Message]) -> bool:
         ordered_group_ids = _ordered_group_ids_from_annotations(messages)
@@ -850,6 +924,13 @@ class TruncationStrategy:
         protected_ids: set[str] = set()
         if self.preserve_system:
             protected_ids = {group_id for group_id in ordered_group_ids if kinds.get(group_id) == "system"}
+        if self.preserve_first_user_group:
+            first_user_group_id = next(
+                (group_id for group_id in ordered_group_ids if kinds.get(group_id) == "user"),
+                None,
+            )
+            if first_user_group_id is not None:
+                protected_ids.add(first_user_group_id)
         protected_ids.update(_minimum_retained_group_ids(messages, ordered_group_ids, kinds))
 
         changed = False
@@ -1472,6 +1553,50 @@ class TokenBudgetComposedStrategy:
         return changed
 
 
+async def _run_compaction_strategy(
+    messages: list[Message],
+    *,
+    strategy: CompactionStrategy,
+    tokenizer: TokenizerProtocol | None = None,
+    phase: str,
+) -> bool:
+    """Apply a strategy and log aggregate metrics when it changes context."""
+    resolved_tokenizer = tokenizer
+    if resolved_tokenizer is None:
+        strategy_tokenizer = getattr(strategy, "tokenizer", None)
+        if isinstance(strategy_tokenizer, TokenizerProtocol):
+            resolved_tokenizer = strategy_tokenizer
+
+    annotate_message_groups(messages)
+    if resolved_tokenizer is not None:
+        annotate_token_counts(messages, tokenizer=resolved_tokenizer)
+    before_message_count = _count_included_messages(messages)
+    before_token_count = included_token_count(messages) if resolved_tokenizer is not None else None
+
+    changed = await strategy(messages)
+    if not changed:
+        return False
+
+    annotate_message_groups(messages)
+    if resolved_tokenizer is not None:
+        annotate_token_counts(messages, tokenizer=resolved_tokenizer)
+    after_message_count = _count_included_messages(messages)
+    after_token_count = included_token_count(messages) if resolved_tokenizer is not None else None
+    strategy_name = getattr(strategy, "__name__", type(strategy).__name__)
+    logger.info(
+        "Compaction applied",
+        extra={
+            "compaction_phase": phase,
+            "compaction_strategy": strategy_name,
+            "compaction_included_messages_before": before_message_count,
+            "compaction_included_messages_after": after_message_count,
+            "compaction_included_tokens_before": before_token_count,
+            "compaction_included_tokens_after": after_token_count,
+        },
+    )
+    return True
+
+
 async def apply_compaction(
     messages: list[Message],
     *,
@@ -1481,10 +1606,12 @@ async def apply_compaction(
     """Apply configured compaction and return projected model-input messages."""
     if strategy is None:
         return messages
-    annotate_message_groups(messages)
-    if tokenizer is not None:
-        annotate_token_counts(messages, tokenizer=tokenizer)
-    await strategy(messages)
+    await _run_compaction_strategy(
+        messages,
+        strategy=strategy,
+        tokenizer=tokenizer,
+        phase="in_run",
+    )
     return project_included_messages(messages)
 
 
@@ -1579,10 +1706,12 @@ class CompactionProvider(ContextProvider):
         if not all_messages:
             return
 
-        annotate_message_groups(all_messages)
-        if self.tokenizer is not None:
-            annotate_token_counts(all_messages, tokenizer=self.tokenizer)
-        await self.before_strategy(all_messages)
+        await _run_compaction_strategy(
+            all_messages,
+            strategy=self.before_strategy,
+            tokenizer=self.tokenizer,
+            phase="before_run",
+        )
 
         projected = project_included_messages(all_messages)
         projected_set = {id(m) for m in projected}
@@ -1611,10 +1740,12 @@ class CompactionProvider(ContextProvider):
             return
         stored_messages: list[Message] = raw_messages  # type: ignore[assignment]
 
-        annotate_message_groups(stored_messages)
-        if self.tokenizer is not None:
-            annotate_token_counts(stored_messages, tokenizer=self.tokenizer)
-        await self.after_strategy(stored_messages)
+        await _run_compaction_strategy(
+            stored_messages,
+            strategy=self.after_strategy,
+            tokenizer=self.tokenizer,
+            phase="after_run",
+        )
 
         # Keep all messages (including excluded) in storage so annotations are
         # preserved. The history provider's ``skip_excluded`` flag controls
@@ -1632,9 +1763,10 @@ class ContextWindowCompactionStrategy:
     2. **Truncation** — removes oldest non-system groups when included tokens
        exceed ``truncation_threshold`` of the input budget.
 
-    The class uses two independent :class:`TokenBudgetComposedStrategy`
-    instances — one per phase — so each fires only when its own threshold
-    is exceeded.
+    Each phase checks its threshold explicitly. Token counts are refreshed
+    after tool-result eviction before deciding whether destructive truncation
+    is necessary. If protected groups still exceed the input budget after
+    truncation, the strategy preserves them and emits a structured warning.
 
     Examples:
         .. code-block:: python
@@ -1663,6 +1795,7 @@ class ContextWindowCompactionStrategy:
         tool_eviction_threshold: float = DEFAULT_TOOL_EVICTION_THRESHOLD,
         truncation_threshold: float = DEFAULT_TRUNCATION_THRESHOLD,
         keep_last_tool_call_groups: int = 4,
+        preserve_first_user_group: bool = False,
     ) -> None:
         """Create a context-window compaction strategy.
 
@@ -1681,6 +1814,8 @@ class ContextWindowCompactionStrategy:
             keep_last_tool_call_groups: Number of most recent tool-call groups
                 to retain verbatim during tool eviction. Older groups are
                 collapsed into summaries. Defaults to 4.
+            preserve_first_user_group: Whether destructive truncation preserves
+                the earliest user group. Defaults to False.
 
         Raises:
             ValueError: If thresholds are out of range or inconsistent.
@@ -1706,24 +1841,18 @@ class ContextWindowCompactionStrategy:
         self.input_budget_tokens = input_budget
         self.tool_eviction_threshold = tool_eviction_threshold
         self.truncation_threshold = truncation_threshold
+        self.tokenizer = resolved_tokenizer
+        self._tool_eviction_tokens = tool_eviction_tokens
+        self._truncation_tokens = truncation_tokens
 
-        self._tool_eviction = TokenBudgetComposedStrategy(
-            token_budget=tool_eviction_tokens,
-            tokenizer=resolved_tokenizer,
-            strategies=[
-                ToolResultCompactionStrategy(keep_last_tool_call_groups=keep_last_tool_call_groups),
-            ],
+        self._tool_eviction = ToolResultCompactionStrategy(
+            keep_last_tool_call_groups=keep_last_tool_call_groups,
         )
-        self._truncation = TokenBudgetComposedStrategy(
-            token_budget=truncation_tokens,
+        self._truncation = TruncationStrategy(
+            max_n=truncation_tokens,
+            compact_to=tool_eviction_tokens,
             tokenizer=resolved_tokenizer,
-            strategies=[
-                TruncationStrategy(
-                    max_n=truncation_tokens,
-                    compact_to=tool_eviction_tokens,
-                    tokenizer=resolved_tokenizer,
-                ),
-            ],
+            preserve_first_user_group=preserve_first_user_group,
         )
 
     async def __call__(self, messages: list[Message]) -> bool:
@@ -1732,8 +1861,28 @@ class ContextWindowCompactionStrategy:
         Returns:
             True if compaction changed message inclusion; otherwise False.
         """
-        changed = await self._tool_eviction(messages)
-        return (await self._truncation(messages)) or changed
+        annotate_message_groups(messages)
+        annotate_token_counts(messages, tokenizer=self.tokenizer)
+
+        changed = False
+        if included_token_count(messages) > self._tool_eviction_tokens:
+            changed = await self._tool_eviction(messages)
+            annotate_message_groups(messages)
+            annotate_token_counts(messages, tokenizer=self.tokenizer)
+
+        if included_token_count(messages) > self._truncation_tokens:
+            changed = (await self._truncation(messages)) or changed
+        remaining_tokens = included_token_count(messages)
+        if remaining_tokens > self.input_budget_tokens:
+            logger.warning(
+                "Compaction could not fit protected messages within the input budget",
+                extra={
+                    "compaction_strategy": type(self).__name__,
+                    "compaction_included_tokens_after": remaining_tokens,
+                    "compaction_input_budget_tokens": self.input_budget_tokens,
+                },
+            )
+        return changed
 
 
 __all__ = [

{agent_framework_core-1.16.0 → agent_framework_core-1.17.0}/agent_framework/_harness/_agent.py

@@ -20,6 +20,7 @@ from .._agents import Agent, SupportsAgentRun
 from .._clients import SupportsShellTool, SupportsWebSearchTool
 from .._compaction import CompactionProvider, ContextWindowCompactionStrategy
 from .._feature_stage import ExperimentalFeature, warn_experimental_feature
+from .._middleware import _copy_middleware_sequence  # pyright: ignore[reportPrivateUsage]
 from .._sessions import ContextProvider, HistoryProvider, InMemoryHistoryProvider, MessageInjectionMiddleware
 from .._skills import SkillsProvider
 from .._telemetry import FeatureIndex, mark_feature_used
@@ -347,7 +348,7 @@ def create_harness_agent(
     loop_max_iterations: int | None = DEFAULT_MAX_ITERATIONS,
     otel_provider_name: str | None = None,
     context_providers: Sequence[ContextProvider] | None = None,
-    middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+    middleware: Sequence[MiddlewareTypes] | None = None,
     default_options: Mapping[str, Any] | None = None,
 ) -> Agent[OptionsCoT]:
     """Create a pre-configured agent with batteries included.
@@ -669,11 +670,8 @@ def create_harness_agent(
     # Message injection is always on. It is a no-op when no messages are queued for the session,
     # so there is no opt-out.
     assembled_middleware.append(MessageInjectionMiddleware())
-    # Bare-source normalization (a single middleware object or a MiddlewareBundle is
-    # one element) is owned by _as_middleware_list.
-    from .._middleware import _as_middleware_list  # pyright: ignore[reportPrivateUsage]
-
-    assembled_middleware.extend(_as_middleware_list(middleware))
+    if middleware is not None:
+        assembled_middleware.extend(_copy_middleware_sequence(middleware))
 
     agent = Agent(
         client,