Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

fix(session): harden lifecycle isolation

xfgong9134da771b44
diff --git a/cubeloop/agent/agent.py b/cubeloop/agent/agent.py
index 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.py
index 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_attempt
async def _capture_model_attempt(model_spec) -> None:
+ from cubeloop.providers.fallback import get_attempt_index
from cubeloop.session.turn_execution_context import TurnExecutionContext
existing = 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 None
or 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.extra
else None
),
+ model_attempt_id=model_attempt_id,
)
context.turn_id = turn_id
context.turn_execution_context = captured
diff --git a/cubeloop/agent/tools.py b/cubeloop/agent/tools.py
index 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.py
index 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 = None
first: StreamEvent | None = None
try:
- 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 = exc
else:
diff --git a/cubeloop/session/session.py b/cubeloop/session/session.py
index b6eb4ec..de0c7bf 100644
--- a/cubeloop/session/session.py
+++ b/cubeloop/session/session.py
@@ -6,9 +6,12 @@ from collections.abc import Callable
from dataclasses import dataclass, replace
from 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, MessageEndEvent
from cubeloop.checkpointer.base import CheckpointData
+from cubeloop.hitl.types import HitlRequest
from cubeloop.session.events import (
ExecutionEventEnvelope,
ExecutionFinished,
@@ -77,6 +80,8 @@ class ExecutionSession:
self._active_run_id: str | None = None
self._cancel_requested = False
self._accepting_input = False
+ self._idle = asyncio.Event()
+ self._idle.set()
self._seq = 0
self._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
@property
def 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] = context
return
@@ -133,6 +139,9 @@ class ExecutionSession:
self._cancel_requested = True
self._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_id
self._active_run_id = request.run_id
self._cancel_requested = False
@@ -250,12 +260,14 @@ class ExecutionSession:
self._seq = 0
self._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 = None
caught: BaseException | None = None
try:
if isinstance(request, PromptExecutionRequest):
@@ -318,6 +330,7 @@ class ExecutionSession:
finally:
self._active_attempt_id = None
self._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:
return
if 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_id
await 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_request
private_outcome = self._agent.state.last_outcome
error: 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.py
index 40fbc4e..8bff829 100644
--- a/cubeloop/session/turn_execution_context.py
+++ b/cubeloop/session/turn_execution_context.py
@@ -3,7 +3,7 @@ from __future__ import annotations
from dataclasses import dataclass, field, replace
from types import MappingProxyType
from collections.abc import Awaitable, Callable
-from typing import Any, Mapping
+from typing import Any, Literal, Mapping
from 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
@classmethod
def 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.py
index 9099915..62ea22b 100644
--- a/tests/agent/test_execution_session.py
+++ b/tests/agent/test_execution_session.py
@@ -7,9 +7,10 @@ import pytest
from cubeloop import Agent
from cubeloop.checkpointer.base import CheckpointData
from 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, InMemoryChannel
from cubeloop.hitl.types import ConfirmRequest, HitlRequest
-from cubeloop.providers.base import AssistantMessage, TextContent, UserMessage
+from cubeloop.providers.base import AssistantMessage, TextContent, ToolCall, UserMessage
from cubeloop.providers.faux import FauxProvider
from 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.asyncio
async 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_id
diff --git a/tests/agent/test_session_events.py b/tests/agent/test_session_events.py
index 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.asyncio
async 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.py
index 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) == 1
assert 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.py
index 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 pytest
from pydantic import BaseModel
@@ -148,6 +150,31 @@ async def test_retry_reuses_context_and_fallback_captures_new_model_view() -> No
assert 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) == 1
assert 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"]