CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
fix(session): harden lifecycle isolation
xfgong9134da771b44
diff --git a/cubeloop/agent/agent.py b/cubeloop/agent/agent.pyindex 3314349..4ba3618 100644--- a/cubeloop/agent/agent.py+++ b/cubeloop/agent/agent.py@@ -356,8 +356,7 @@ class Agent(Generic[TMessage]):self._active_signal.set()async def wait_for_idle(self) -> None:- if self._active_done:- await self._active_done.wait()+ await self.session.wait_for_idle()def reset(self) -> None:self._state._messages = []diff --git a/cubeloop/agent/loop.py b/cubeloop/agent/loop.pyindex 76f21c0..ffba3f9 100644--- a/cubeloop/agent/loop.py+++ b/cubeloop/agent/loop.py@@ -774,14 +774,18 @@ async def _stream_assistant_response(previous_on_model_attempt = options.on_model_attemptasync def _capture_model_attempt(model_spec) -> None:+ from cubeloop.providers.fallback import get_attempt_indexfrom cubeloop.session.turn_execution_context import TurnExecutionContextexisting = context.turn_execution_context+ fallback_index = get_attempt_index()+ model_attempt_id = (+ f"fallback:{fallback_index}" if fallback_index is not None else None+ )if (existing is Noneor existing.turn_id != turn_id- or existing.model.id != model_spec.id- or existing.model.provider_id != model_spec.provider_id+ or not existing.matches_model(model_spec, model_attempt_id)):captured = TurnExecutionContext.capture(turn_id=turn_id,@@ -797,6 +801,7 @@ async def _stream_assistant_response(if "policy_revision" in context.extraelse None),+ model_attempt_id=model_attempt_id,)context.turn_id = turn_idcontext.turn_execution_context = captureddiff --git a/cubeloop/agent/tools.py b/cubeloop/agent/tools.pyindex 7b1708c..756985a 100644--- a/cubeloop/agent/tools.py+++ b/cubeloop/agent/tools.py@@ -403,6 +403,19 @@ def _should_terminate(finalized: list[_FinalizedOutcome]) -> bool:return len(finalized) > 0 and all(f.result.terminate is True for f in finalized)+def _execution_mode_for(context: AgentContext, tool_name: str) -> str | None:+ turn_context = context.turn_execution_context+ if turn_context is not None:+ binding = turn_context.binding_for(tool_name)+ if binding is not None:+ return binding.execution_mode+ if context.tools:+ tool = next((tool for tool in context.tools if tool.name == tool_name), None)+ if tool is not None:+ return tool.execution_mode+ return None++async def execute_tool_calls(context: AgentContext,assistant_message: AssistantMessage,@@ -417,11 +430,7 @@ async def execute_tool_calls(tool_calls = [c for c in assistant_message.content if isinstance(c, ToolCall)]has_sequential_raw = any(- t.execution_mode == "sequential"- for tc in tool_calls- if context.tools- for t in context.tools- if t.name == tc.name+ _execution_mode_for(context, call.name) == "sequential" for call in tool_calls)if tool_execution == "sequential" or has_sequential_raw:@@ -451,11 +460,8 @@ async def execute_tool_calls()has_sequential_resolved = any(- t.execution_mode == "sequential"- for (rtc, _, _) in resolutions- if context.tools- for t in context.tools- if t.name == rtc.name+ _execution_mode_for(context, call.name) == "sequential"+ for call, _, _ in resolutions)if has_sequential_resolved:diff --git a/cubeloop/providers/fallback.py b/cubeloop/providers/fallback.pyindex 39cabb3..aa5414d 100644--- a/cubeloop/providers/fallback.py+++ b/cubeloop/providers/fallback.py@@ -74,6 +74,9 @@ class _FallbackRunState:_run_state: contextvars.ContextVar[_FallbackRunState | None] = contextvars.ContextVar("cubepi_fallback_run_state", default=None)+_attempt_index: contextvars.ContextVar[int | None] = contextvars.ContextVar(+ "cubeloop_fallback_attempt_index", default=None+)def begin_fallback_run() -> contextvars.Token[_FallbackRunState | None]:@@ -101,6 +104,11 @@ def get_active_index() -> int:return 0 if state is None else state.active_index+def get_attempt_index() -> int | None:+ """Return the fallback leg currently entering its bound model."""+ return _attempt_index.get()++def set_active_index(index: int) -> None:"""Restore a previously snapshotted sticky index into the current run."""@@ -395,13 +403,17 @@ class FallbackBoundModel:err: BaseException | None = Nonefirst: StreamEvent | None = Nonetry:- inner = await bound.stream(- messages,- system_prompt=system_prompt,- tools=tools,- tool_choice=tool_choice,- options=options,- )+ attempt_token = _attempt_index.set(index)+ try:+ inner = await bound.stream(+ messages,+ system_prompt=system_prompt,+ tools=tools,+ tool_choice=tool_choice,+ options=options,+ )+ finally:+ _attempt_index.reset(attempt_token)except Exception as exc:err = excelse:diff --git a/cubeloop/session/session.py b/cubeloop/session/session.pyindex b6eb4ec..de0c7bf 100644--- a/cubeloop/session/session.py+++ b/cubeloop/session/session.py@@ -6,9 +6,12 @@ from collections.abc import Callablefrom dataclasses import dataclass, replacefrom typing import TYPE_CHECKING, Any+from pydantic import BaseModel+from cubeloop.agent._tool_cycle import ToolCycleViolation, check_tool_cycle-from cubeloop.agent.types import AgentEndEvent, MessageEndEvent+from cubeloop.agent.types import AgentEndEvent, AgentSuspendedEvent, MessageEndEventfrom cubeloop.checkpointer.base import CheckpointData+from cubeloop.hitl.types import HitlRequestfrom cubeloop.session.events import (ExecutionEventEnvelope,ExecutionFinished,@@ -77,6 +80,8 @@ class ExecutionSession:self._active_run_id: str | None = Noneself._cancel_requested = Falseself._accepting_input = False+ self._idle = asyncio.Event()+ self._idle.set()self._seq = 0self._publish_lock = asyncio.Lock()self._required_delivery_failure: DeliveryError | None = None@@ -84,6 +89,7 @@ class ExecutionSession:self._input_status: dict[str, InputStatus] = {}self._delivery_errors: list[DeliveryError] = []self._turn_contexts: list[TurnExecutionContext] = []+ self._pending_request: HitlRequest | None = None@propertydef active_attempt_id(self) -> str | None:@@ -98,8 +104,8 @@ class ExecutionSession:existing = self._turn_contexts[index]if (existing.turn_id == context.turn_id- and existing.model.id == context.model.id- and existing.model.provider_id == context.model.provider_id+ and existing.model == context.model+ and existing.model_attempt_id == context.model_attempt_id):self._turn_contexts[index] = contextreturn@@ -133,6 +139,9 @@ class ExecutionSession:self._cancel_requested = Trueself._agent.abort()+ async def wait_for_idle(self) -> None:+ await self._idle.wait()+async def request_detach(self) -> None:if self._agent.channel is None or self._agent.channel.pending is None:raise RuntimeError("execution can detach only at a pending HITL safe point")@@ -243,6 +252,7 @@ class ExecutionSession:"""Execute one attempt and return settled lifecycle facts."""self._assert_idle()+ self._idle.clear()self._active_attempt_id = request.attempt_idself._active_run_id = request.run_idself._cancel_requested = False@@ -250,12 +260,14 @@ class ExecutionSession:self._seq = 0self._delivery_errors = []self._required_delivery_failure = None- self._input_status = {- input_id: status- for input_id, status in self._input_status.items()- if status != "queued"- }+ for input_id, status in tuple(self._input_status.items()):+ if status != "queued":+ continue+ self._agent._steering_queue.remove(input_id)+ self._agent._follow_up_queue.remove(input_id)+ del self._input_status[input_id]self._turn_contexts.clear()+ self._pending_request = Nonecaught: BaseException | None = Nonetry:if isinstance(request, PromptExecutionRequest):@@ -318,6 +330,7 @@ class ExecutionSession:finally:self._active_attempt_id = Noneself._active_run_id = None+ self._idle.set()def _assert_idle(self) -> None:if self._active_attempt_id is not None or self._agent._run_lock.locked():@@ -350,21 +363,25 @@ class ExecutionSession:returnif isinstance(event, AgentEndEvent):self._accepting_input = False+ if isinstance(event, AgentSuspendedEvent):+ self._pending_request = event.pending_request.model_copy(deep=True)+ committed_input_id: str | None = None+ if isinstance(event, MessageEndEvent):+ input_id = event.message.metadata.get("input_id")+ if (+ isinstance(input_id, str)+ and self._input_status.get(input_id) == "queued"+ ):+ self._input_status[input_id] = "committed"+ committed_input_id = input_idawait self._publish(event, terminal=False)- if not isinstance(event, MessageEndEvent):- return- message = event.message- input_id = message.metadata.get("input_id")- if not isinstance(input_id, str):+ if committed_input_id is None:return- if self._input_status.get(input_id) != "queued":- return- self._input_status[input_id] = "committed"durability: InputDurability = ("checkpoint" if self._has_durable_checkpoint() else "memory")await self._publish(- InputCommitted(input_id=input_id, durability=durability),+ InputCommitted(input_id=committed_input_id, durability=durability),terminal=False,)@@ -404,7 +421,10 @@ class ExecutionSession:if consumer.task is None:consumer.task = asyncio.create_task(self._consume(consumer))acknowledged = asyncio.get_running_loop().create_future()- item = _DeliveryItem(envelope=envelope, acknowledged=acknowledged)+ item = _DeliveryItem(+ envelope=self._snapshot_envelope(envelope),+ acknowledged=acknowledged,+ )await asyncio.wait_for(consumer.queue.put(item),timeout=consumer.delivery_timeout,@@ -444,6 +464,24 @@ class ExecutionSession:)return errors+ @staticmethod+ def _snapshot_envelope(+ envelope: ExecutionEventEnvelope,+ ) -> ExecutionEventEnvelope:+ event = envelope.event+ if isinstance(event, BaseModel):+ event = event.model_copy(deep=True)+ elif isinstance(event, ExecutionFinished):+ pending = event.result.pending_request+ result = replace(+ event.result,+ pending_request=(+ pending.model_copy(deep=True) if pending is not None else None+ ),+ )+ event = ExecutionFinished(result=result)+ return replace(envelope, event=event)+async def _consume(self, consumer: _Consumer) -> None:while True:item = await consumer.queue.get()@@ -499,6 +537,8 @@ class ExecutionSession:if load_pending is not None:loaded = await load_pending(self._agent.thread_id)pending = loaded[0] if loaded is not None else None+ if pending is None:+ pending = self._pending_requestprivate_outcome = self._agent.state.last_outcomeerror: ExecutionError | None = None@@ -514,18 +554,18 @@ class ExecutionSession:elif caught is not None:outcome = "failed"error = ExecutionError(- kind="finalization",+ kind="execution",message=str(caught),cause=caught,)+ elif private_outcome == "suspended":+ outcome = "suspended"elif not history_consistent or private_outcome == "incomplete":outcome = "incomplete"error = ExecutionError(kind="inconsistent",message="execution history has incomplete tool-call results",)- elif private_outcome == "suspended":- outcome = "suspended"elif private_outcome == "complete" and not self._agent.state.error_message:outcome = "completed"else:diff --git a/cubeloop/session/turn_execution_context.py b/cubeloop/session/turn_execution_context.pyindex 40fbc4e..8bff829 100644--- a/cubeloop/session/turn_execution_context.py+++ b/cubeloop/session/turn_execution_context.py@@ -3,7 +3,7 @@ from __future__ import annotationsfrom dataclasses import dataclass, field, replacefrom types import MappingProxyTypefrom collections.abc import Awaitable, Callable-from typing import Any, Mapping+from typing import Any, Literal, Mappingfrom pydantic import BaseModel@@ -70,6 +70,7 @@ class ToolExecutionBinding:parameters: type[BaseModel]execute: Callable[..., Awaitable[AgentToolResult]]hitl_builtin: bool+ execution_mode: Literal["sequential", "parallel"] | None_source_id: int = field(repr=False)@classmethod@@ -80,6 +81,7 @@ class ToolExecutionBinding:parameters=tool.parameters,execute=tool.execute,hitl_builtin=tool.hitl_builtin,+ execution_mode=tool.execution_mode,_source_id=id(tool),)@@ -95,6 +97,7 @@ class TurnExecutionContext:messages: tuple[MessageView, ...]tools: tuple[ToolExecutionBinding, ...]policy_revision: str | None = None+ model_attempt_id: str | None = None@classmethoddef capture(@@ -109,6 +112,7 @@ class TurnExecutionContext:messages: list[Message],tools: list[AgentTool] | None,policy_revision: str | None = None,+ model_attempt_id: str | None = None,) -> TurnExecutionContext:return cls(turn_id=turn_id,@@ -120,6 +124,12 @@ class TurnExecutionContext:messages=tuple(MessageView.capture(message) for message in messages),tools=tuple(ToolExecutionBinding.capture(tool) for tool in tools or []),policy_revision=policy_revision,+ model_attempt_id=model_attempt_id,+ )++ def matches_model(self, model: Model, model_attempt_id: str | None) -> bool:+ return (+ self.model == _freeze(model) and self.model_attempt_id == model_attempt_id)def binding_for(self, name: str) -> ToolExecutionBinding | None:diff --git a/dev/plans/2026-09-14-execution-session.md b/dev/plans/2026-09-14-execution-session.mdnew file mode 100644index 0000000..065612d--- /dev/null+++ b/dev/plans/2026-09-14-execution-session.md@@ -0,0 +1,48 @@+# Execution Session Lifecycle Implementation Plan++## Goal++Add a public, host-facing execution lifecycle without moving product-specific+durability or transport policy into CubeLoop.++## Work++1. Define typed execution requests, results, errors, input envelopes and+ receipts, event envelopes, and turn execution contexts under+ `cubeloop/session/`; export them from the package root.+2. Give every `Agent` an `ExecutionSession`; route prompt, respond, and continue+ through one fail-fast admission gate while retaining the existing internal+ loop and checkpoint behavior.+3. Implement checkpoint loading and stable live `state_context` binding without+ exposing host code to `Agent._state` or `Agent._extra`.+4. Add bounded subscriber queues, finite acknowledgement timeouts, required and+ optional consumer semantics, isolated event snapshots, monotonic sequence+ numbers, and exactly one terminal event.+5. Add concurrent steer/follow-up submission with bounded cross-attempt+ deduplication, cancellation, run-ID validation, persistence-before-commit+ ordering, and stale-queue cleanup.+6. Capture immutable effective model requests and executable tool bindings,+ including fallback-leg identity and dynamically resolved tools.+7. Return explicit completed, suspended, cancelled, failed, and incomplete+ results. Preserve pending in-memory and checkpointed HITL requests and keep+ terminal publication alive through cancellation.+8. Extend `Agent.wait_for_idle()` through session finalization.+9. Document the public lifecycle in English and Simplified Chinese, including+ the cross-process tool-catalog reconstruction boundary.++## Verification++- Unit tests cover admission, input receipt transitions, cross-attempt+ deduplication, cancellation, HITL detach/respond, event isolation and delivery+ failure, terminal publication, immutable tool bindings, and fallback capture.+- Run ruff formatting and lint, strict mypy for the changed runtime modules, the+ complete Python test suite, both Docusaurus locale builds, and Codecov patch+ coverage.+- After every pushed fix, reply to each PR comment and request another Codex+ review until the latest commit receives no actionable feedback.++## Out of scope++- Persisting Python tool callbacks or the complete `TurnExecutionContext`.+- Product-specific Redis, SSE, database, and queue adapters.+- Parallel subagent orchestration.diff --git a/dev/specs/2026-09-14-execution-session.md b/dev/specs/2026-09-14-execution-session.mdnew file mode 100644index 0000000..c7bbb50--- /dev/null+++ b/dev/specs/2026-09-14-execution-session.md@@ -0,0 +1,82 @@+# Execution Session Lifecycle++## Problem++`Agent.prompt()`, `respond()`, and `resume()` historically exposed the agent loop+directly. A host runtime could observe agent events, but it had no public object+that owned one execution attempt, accepted concurrent input, reported durability,+or returned a settled terminal result. Hosts therefore depended on private agent+state and could not distinguish execution failure, suspension, cancellation,+incomplete history, finalization failure, or event-delivery failure.++## Contract++Every `Agent` owns one `ExecutionSession`. The session accepts typed prompt,+respond, and continue requests. A request carries a stable `run_id` and a unique+`attempt_id`; only one attempt may execute or finalize at a time. Existing+`Agent` entry points delegate to this same admission gate.++`execute()` always settles ordinary execution and cancellation into an immutable+`ExecutionResult`. The result reports the outcome, pending HITL request when+suspended, checkpoint commitment, history consistency, a typed error, and any+consumer-delivery diagnostics. Process-control exceptions such as+`KeyboardInterrupt` and `SystemExit` are not converted.++`wait_for_idle()` covers the complete session lifecycle, including checkpoint+settlement and terminal consumer delivery. A caller released by it may start the+next attempt without racing finalization.++## Input and durability++While admission is open, a host may submit a steer or follow-up message with an+idempotency key. The receipt is `queued`, `committed`, `cancelled`, or `closed`.+The session stamps the active run and input identity, rejects conflicting run+IDs, and keeps a bounded terminal receipt ledger across attempts.++An input becomes committed immediately after the agent has appended it to its+history, before external event delivery. `InputCommitted` is then published in+normal message-event order. Failed or cancelled attempts remove undrained queue+entries before the next attempt, so stale input cannot leak into another run.+Checkpoint-backed agents report checkpoint durability; other agents report+in-memory durability.++## Event delivery++Subscribers receive monotonic, attempt-scoped `ExecutionEventEnvelope` values.+Each subscriber has a bounded queue and finite delivery timeout. Required+consumer failure stops non-terminal publication and fails the attempt, while+terminal publication is still attempted exactly once. Each consumer receives an+isolated snapshot, so it cannot mutate agent state or another consumer's view.++`ExecutionFinished` is a session lifecycle event, not a product transport's+user-facing completion event. Hosts remain responsible for projecting events to+their own durable log or SSE protocol.++## Turn execution context++Each concrete model request captures an immutable `TurnExecutionContext`:+effective model and reasoning settings, transformed prompt and messages, policy+revision, and frozen tool execution bindings. A binding fixes the schema,+validator, callback, HITL flag, and execution mode used for that request.++Retries on one fallback leg reuse its capture. A different fallback leg receives+a distinct identity even when two legs advertise identical provider and model+labels. Dynamically resolved tools extend the captured context without rebinding+an existing name.++The full context and executable callbacks are process-local. Checkpoints persist+conversation and extra state, not Python callables. A host resuming on another+process must reconstruct the same pinned/versioned tool catalog.++## HITL++Detach is valid only at a pending HITL safe point. The session preserves the+pending request from the committed suspension event, including for an+`InMemoryChannel`, and returns it in the suspended result. Respond requests+validate the recovered run ID under the execution lock before consuming an+answer.++## Compatibility++No storage schema, provider wire format, or existing agent event type changes.+Existing `Agent` methods remain available and delegate through the session.diff --git a/tests/agent/test_execution_session.py b/tests/agent/test_execution_session.pyindex 9099915..62ea22b 100644--- a/tests/agent/test_execution_session.py+++ b/tests/agent/test_execution_session.py@@ -7,9 +7,10 @@ import pytestfrom cubeloop import Agentfrom cubeloop.checkpointer.base import CheckpointDatafrom cubeloop.checkpointer.memory import MemoryCheckpointer-from cubeloop.hitl.channel import CheckpointedChannel+from cubeloop.hitl.ask_user import ask_user_tool+from cubeloop.hitl.channel import CheckpointedChannel, InMemoryChannelfrom cubeloop.hitl.types import ConfirmRequest, HitlRequest-from cubeloop.providers.base import AssistantMessage, TextContent, UserMessage+from cubeloop.providers.base import AssistantMessage, TextContent, ToolCall, UserMessagefrom cubeloop.providers.faux import FauxProviderfrom cubeloop.session import (ExecutionBusy,@@ -263,6 +264,29 @@ async def test_agent_respond_checks_admission_before_loading_pending() -> None:assert await active == "run-1"+async def test_wait_for_idle_includes_terminal_session_delivery() -> None:+ terminal_entered = asyncio.Event()+ release_terminal = asyncio.Event()++ async def listener(envelope):+ if envelope.event.type == "execution_finished":+ terminal_entered.set()+ await release_terminal.wait()++ agent = Agent(model=_provider(_answer()).model("faux-model"))+ agent.session.subscribe(listener)+ execution = asyncio.create_task(agent.prompt("hi", run_id="run-1"))+ await asyncio.wait_for(terminal_entered.wait(), timeout=1)+ idle = asyncio.create_task(agent.wait_for_idle())+ await asyncio.sleep(0)++ assert not idle.done()+ release_terminal.set()+ assert await execution == "run-1"+ await idle++@pytest.mark.asyncioasync def test_load_checkpoint_restores_extra_in_place_even_without_messages() -> None:checkpointer = MemoryCheckpointer()@@ -405,3 +429,43 @@ async def test_detach_rejects_outside_hitl_safe_point() -> None:with pytest.raises(RuntimeError, match="HITL safe point"):await agent.session.request_detach()+++async def test_in_memory_detach_returns_pending_request() -> None:+ channel = InMemoryChannel(thread_id="thread-1")+ provider = _provider(+ AssistantMessage(+ content=[+ ToolCall(+ id="ask-1",+ name="ask_user",+ arguments={"questions": [{"key": "answer", "prompt": "Continue?"}]},+ )+ ],+ stop_reason="tool_use",+ )+ )+ agent = Agent(+ model=provider.model("faux-model"),+ tools=[ask_user_tool(channel)],+ channel=channel,+ )+ execution = asyncio.create_task(+ agent.session.execute(+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi")+ )+ )+ for _ in range(100):+ if channel.pending is not None:+ break+ await asyncio.sleep(0.01)+ assert channel.pending is not None+ question_id = channel.pending.question_id++ await agent.session.request_detach()+ result = await execution++ assert result.outcome == "suspended"+ assert result.pending_request is not None+ assert result.pending_request.question_id == question_iddiff --git a/tests/agent/test_session_events.py b/tests/agent/test_session_events.pyindex fe886a4..48a32c7 100644--- a/tests/agent/test_session_events.py+++ b/tests/agent/test_session_events.py@@ -54,9 +54,80 @@ async def test_required_consumer_failure_fails_execution() -> None:assert result.outcome == "failed"assert result.error is not None+ assert result.error.kind == "execution"assert "host-publisher" in result.error.message+async def test_persisted_input_is_committed_before_required_delivery_failure() -> None:+ entered = asyncio.Event()+ release = asyncio.Event()++ async def first_response(messages, model):+ del messages, model+ entered.set()+ await release.wait()+ return AssistantMessage(+ content=[TextContent(text="first")], stop_reason="end_turn"+ )++ provider = FauxProvider(provider_id="faux")+ provider.set_responses([first_response])+ agent = Agent(model=provider.model("faux-model"))++ async def fail_on_input(envelope):+ event = envelope.event+ if (+ event.type == "message_end"+ and event.message.metadata.get("input_id") == "input-1"+ ):+ raise RuntimeError("host unavailable")++ agent.session.subscribe(fail_on_input, required=True, name="host")+ task = asyncio.create_task(+ agent.session.execute(+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi")+ )+ )+ await asyncio.wait_for(entered.wait(), timeout=1)+ envelope = InputEnvelope(+ input_id="input-1",+ message=UserMessage(content=[TextContent(text="persist once")]),+ mode="follow_up",+ )+ assert agent.session.submit_input(envelope).status == "queued"+ release.set()++ result = await task++ assert result.outcome == "failed"+ assert agent.session.submit_input(envelope).status == "committed"+++async def test_consumers_receive_isolated_agent_event_snapshots() -> None:+ agent = _agent()+ observed = []++ def mutate_first(envelope):+ event = envelope.event+ if event.type == "message_start" and event.message.role == "user":+ event.message.content[0].text = "mutated"++ def observe_second(envelope):+ event = envelope.event+ if event.type == "message_start" and event.message.role == "user":+ observed.append(event.message.content[0].text)++ agent.session.subscribe(mutate_first, name="mutator")+ agent.session.subscribe(observe_second, name="observer")++ await agent.prompt("original", run_id="run-1")++ assert observed == ["original"]+ assert agent.state.messages[0].content[0].text == "original"++@pytest.mark.asyncioasync def test_final_notification_timeout_preserves_settled_result() -> None:agent = _agent()diff --git a/tests/agent/test_session_input.py b/tests/agent/test_session_input.pyindex 2868c8f..cab7359 100644--- a/tests/agent/test_session_input.py+++ b/tests/agent/test_session_input.py@@ -435,3 +435,47 @@ async def test_error_response_closes_input_before_agent_end_delivery() -> None:assert result.outcome == "failed"assert len(receipts) == 1assert receipts[0].status == "closed"+++async def test_cancelled_attempt_discards_its_undrained_input_queue() -> None:+ first_entered = asyncio.Event()+ second_entered = asyncio.Event()+ release_second = asyncio.Event()++ async def first_response(messages, model):+ del messages, model+ first_entered.set()+ await asyncio.Future()++ async def second_response(messages, model):+ del messages, model+ second_entered.set()+ await release_second.wait()+ return AssistantMessage(+ content=[TextContent(text="done")], stop_reason="end_turn"+ )++ provider = FauxProvider(provider_id="faux")+ provider.set_responses([first_response, second_response])+ agent = Agent(model=provider.model("faux-model"))+ first = asyncio.create_task(agent.prompt("first", run_id="run-1"))+ await asyncio.wait_for(first_entered.wait(), timeout=1)+ envelope = InputEnvelope(+ input_id="retry-id",+ message=UserMessage(content=[TextContent(text="stale")]),+ mode="follow_up",+ )+ assert agent.session.submit_input(envelope).status == "queued"+ first.cancel()+ with pytest.raises(asyncio.CancelledError):+ await first++ second = asyncio.create_task(agent.prompt("second", run_id="run-2"))+ await asyncio.wait_for(second_entered.wait(), timeout=1)++ assert not agent._follow_up_queue.has_items()+ assert agent.session.submit_input(envelope).status == "queued"+ assert agent.session.cancel_input("retry-id").status == "cancelled"+ release_second.set()+ assert await second == "run-2"diff --git a/tests/agent/test_turn_execution_context.py b/tests/agent/test_turn_execution_context.pyindex 0c1e4c2..f64d53b 100644--- a/tests/agent/test_turn_execution_context.py+++ b/tests/agent/test_turn_execution_context.py@@ -1,5 +1,7 @@from __future__ import annotations+import asyncio+import pytestfrom pydantic import BaseModel@@ -148,6 +150,31 @@ async def test_retry_reuses_context_and_fallback_captures_new_model_view() -> Noassert contexts[0].turn_id == contexts[1].turn_id+async def test_fallback_legs_with_identical_model_specs_capture_separately() -> None:+ primary = FauxProvider(provider_id="same").model("same-model")+ fallback_provider = FauxProvider(provider_id="same")+ fallback_provider.set_responses(+ [AssistantMessage(content=[TextContent(text="done")], stop_reason="end_turn")]+ )+ agent = Agent(+ model=FallbackBoundModel(+ chain=(primary, fallback_provider.model("same-model")),+ max_retries_per_model=0,+ )+ )++ await agent.prompt("hi", run_id="run-1")++ contexts = agent.session.turn_contexts+ assert len(contexts) == 2+ assert [context.model_attempt_id for context in contexts] == [+ "fallback:0",+ "fallback:1",+ ]+ assert contexts[0].turn_id == contexts[1].turn_id++def test_turn_context_extension_is_immutable_and_rejects_rebinding() -> None:async def execute(tool_call_id, args, *, signal=None, on_update=None):del tool_call_id, args, signal, on_update@@ -253,3 +280,56 @@ async def test_resolved_tool_extension_updates_public_session_context() -> None:assert len(agent.session.turn_contexts) == 1assert agent.session.turn_contexts[0].binding_for("work") is not None+++async def test_tool_batch_uses_captured_execution_mode() -> None:+ order = []++ async def execute(tool_call_id, args, *, signal=None, on_update=None):+ del tool_call_id, signal, on_update+ order.append(f"start:{args.value}")+ await asyncio.sleep(0)+ order.append(f"end:{args.value}")+ return AgentToolResult(content=[TextContent(text="done")])++ tool = AgentTool(+ name="work",+ description="work",+ parameters=_Args,+ execute=execute,+ execution_mode="sequential",+ )+ provider = FauxProvider(provider_id="faux")+ captured = TurnExecutionContext.capture(+ turn_id="turn-1",+ run_id="run-1",+ attempt_id="attempt-1",+ model=provider.model("faux-model").spec,+ reasoning=ReasoningControl(),+ system_prompt="",+ messages=[],+ tools=[tool],+ )+ context = AgentContext(+ system_prompt="",+ messages=[],+ tools=[tool],+ turn_execution_context=captured,+ )+ tool.execution_mode = "parallel"++ await execute_tool_calls(+ context,+ AssistantMessage(+ content=[+ ToolCall(id="call-1", name="work", arguments={"value": "a"}),+ ToolCall(id="call-2", name="work", arguments={"value": "b"}),+ ],+ stop_reason="tool_use",+ ),+ tool_execution="parallel",+ emit=lambda event: None,+ )++ assert order == ["start:a", "end:a", "start:b", "end:b"]