Skip to content

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

fix(session): preserve terminal delivery invariants

xfgongc672433650bb
diff --git a/cubeloop/agent/agent.py b/cubeloop/agent/agent.py
index 9b3b5c8..a084bfe 100644
--- a/cubeloop/agent/agent.py
+++ b/cubeloop/agent/agent.py
@@ -486,6 +486,7 @@ class Agent(Generic[TMessage]):
) -> str:
from cubeloop.session import PromptExecutionRequest
+ self.session._assert_idle()
self._validate_hitl_bindings(run_id, caller="prompt")
effective_run_id = run_id or uuid.uuid4().hex
result = await self.session.execute(
diff --git a/cubeloop/session/session.py b/cubeloop/session/session.py
index 94cd5ae..11b1a81 100644
--- a/cubeloop/session/session.py
+++ b/cubeloop/session/session.py
@@ -86,7 +86,7 @@ class ExecutionSession:
self._idle.set()
self._seq = 0
self._publish_lock = asyncio.Lock()
- self._required_delivery_failure: DeliveryError | None = None
+ self._required_delivery_failure: tuple[_Consumer, DeliveryError] | None = None
self._consumers: list[_Consumer] = []
self._input_status: dict[str, InputStatus] = {}
self._queued_inputs: dict[str, Message] = {}
@@ -182,6 +182,11 @@ class ExecutionSession:
consumer.task.cancel()
if consumer in self._consumers:
self._consumers.remove(consumer)
+ if (
+ self._required_delivery_failure is not None
+ and self._required_delivery_failure[0] is consumer
+ ):
+ self._required_delivery_failure = None
return unsubscribe
@@ -270,7 +275,6 @@ class ExecutionSession:
self._accepting_input = True
self._seq = 0
self._delivery_errors = []
- self._required_delivery_failure = None
for input_id, status in tuple(self._input_status.items()):
if status != "queued":
continue
@@ -380,7 +384,7 @@ class ExecutionSession:
async def _publish_agent_event(self, event: SessionEvent) -> None:
if self._active_attempt_id is None:
return
- if isinstance(event, AgentEndEvent):
+ if isinstance(event, (AgentEndEvent, AgentSuspendedEvent)):
self._accepting_input = False
self._accepting_cancel = False
if isinstance(event, AgentSuspendedEvent):
@@ -423,7 +427,7 @@ class ExecutionSession:
terminal: bool,
) -> list[DeliveryError]:
if not terminal and self._required_delivery_failure is not None:
- failure = self._required_delivery_failure
+ _, failure = self._required_delivery_failure
raise _RequiredConsumerError(
f"required consumer {failure.consumer} failed: {failure.message}"
)
@@ -435,7 +439,7 @@ class ExecutionSession:
event=event,
)
errors: list[DeliveryError] = []
- required_failure: DeliveryError | None = None
+ required_failure: tuple[_Consumer, DeliveryError] | None = None
for consumer in tuple(self._consumers):
if consumer.closed:
continue
@@ -456,6 +460,7 @@ class ExecutionSession:
timeout=consumer.delivery_timeout,
)
except TimeoutError:
+ acknowledged.cancel()
diagnostic = DeliveryError(
consumer=consumer.name,
seq=envelope.seq,
@@ -465,7 +470,7 @@ class ExecutionSession:
errors.append(diagnostic)
self._close_consumer(consumer)
if consumer.required and not terminal and required_failure is None:
- required_failure = diagnostic
+ required_failure = (consumer, diagnostic)
except Exception as exc:
diagnostic = DeliveryError(
consumer=consumer.name,
@@ -476,13 +481,13 @@ class ExecutionSession:
errors.append(diagnostic)
self._close_consumer(consumer)
if consumer.required and not terminal and required_failure is None:
- required_failure = diagnostic
+ required_failure = (consumer, diagnostic)
self._delivery_errors.extend(errors)
if required_failure is not None:
+ failed_consumer, diagnostic = required_failure
self._required_delivery_failure = required_failure
raise _RequiredConsumerError(
- f"required consumer {required_failure.consumer} failed: "
- f"{required_failure.message}"
+ f"required consumer {failed_consumer.name} failed: {diagnostic.message}"
)
return errors
@@ -569,7 +574,7 @@ class ExecutionSession:
private_outcome = self._agent.state.last_outcome
error: ExecutionError | None = None
- if isinstance(caught, asyncio.CancelledError) or self._cancel_requested:
+ if isinstance(caught, asyncio.CancelledError):
outcome: ExecutionOutcome = "cancelled"
error = ExecutionError(
kind="cancelled",
@@ -583,6 +588,14 @@ class ExecutionSession:
message=str(caught),
cause=caught,
)
+ elif private_outcome == "complete" and not self._agent.state.error_message:
+ outcome = "completed"
+ elif self._cancel_requested:
+ outcome = "cancelled"
+ error = ExecutionError(
+ kind="cancelled",
+ message="execution cancelled",
+ )
elif private_outcome == "suspended":
outcome = "suspended"
elif not history_consistent or private_outcome == "incomplete":
@@ -591,8 +604,6 @@ class ExecutionSession:
kind="inconsistent",
message="execution history has incomplete tool-call results",
)
- elif private_outcome == "complete" and not self._agent.state.error_message:
- outcome = "completed"
else:
outcome = "failed"
message = (
diff --git a/tests/agent/test_execution_session.py b/tests/agent/test_execution_session.py
index 0b5766b..96a5516 100644
--- a/tests/agent/test_execution_session.py
+++ b/tests/agent/test_execution_session.py
@@ -226,6 +226,42 @@ async def test_agent_prompt_and_session_share_one_admission_gate() -> None:
assert [m.run_id for m in agent.state.messages] == ["run-1", "run-1"]
+async def test_agent_prompt_checks_admission_before_hitl_binding() -> None:
+ entered = asyncio.Event()
+ release = asyncio.Event()
+
+ async def slow_response(messages, model):
+ del messages, model
+ entered.set()
+ await release.wait()
+ return _answer()
+
+ provider = _provider()
+ provider.set_responses([slow_response])
+ checkpointer = MemoryCheckpointer()
+ channel = CheckpointedChannel(
+ checkpointer=checkpointer,
+ thread_id="thread-1",
+ run_id="run-1",
+ )
+ agent = Agent(
+ model=provider.model("faux-model"),
+ tools=[ask_user_tool(channel)],
+ channel=channel,
+ checkpointer=checkpointer,
+ thread_id="thread-1",
+ )
+ active = asyncio.create_task(agent.prompt("first", run_id="run-1"))
+ await asyncio.wait_for(entered.wait(), timeout=1)
+
+ with pytest.raises(ExecutionBusy):
+ await agent.prompt("second")
+
+ release.set()
+ assert await active == "run-1"
+
+
@pytest.mark.asyncio
async def test_agent_respond_checks_admission_before_loading_pending() -> None:
entered = asyncio.Event()
@@ -567,6 +603,25 @@ async def test_cancel_requested_during_startup_reaches_new_run_signal() -> None:
assert result.outcome == "cancelled"
+async def test_committed_completion_takes_precedence_over_cancel_request() -> None:
+ agent = Agent(
+ model=_provider(_answer()).model("faux-model"),
+ checkpointer=MemoryCheckpointer(),
+ thread_id="thread-1",
+ )
+ agent._state.last_outcome = "complete"
+ agent.session._cancel_requested = True
+
+ result = await agent.session._settle(
+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi"),
+ None,
+ )
+
+ assert result.outcome == "completed"
+ assert result.checkpoint_committed is True
+
+
@pytest.mark.asyncio
async def test_process_control_exception_releases_session_ownership() -> None:
class ProcessExit(BaseException):
diff --git a/tests/agent/test_session_events.py b/tests/agent/test_session_events.py
index 30a2678..04b9a30 100644
--- a/tests/agent/test_session_events.py
+++ b/tests/agent/test_session_events.py
@@ -5,8 +5,9 @@ import asyncio
import pytest
from cubeloop import Agent
-from cubeloop.agent.types import AgentStartEvent
+from cubeloop.agent.types import AgentStartEvent, AgentSuspendedEvent
from cubeloop.checkpointer.memory import MemoryCheckpointer
+from cubeloop.hitl.types import ConfirmRequest, HitlRequest
from cubeloop.providers.base import UserMessage
from cubeloop.providers.base import AssistantMessage, TextContent
from cubeloop.providers.faux import FauxProvider
@@ -59,6 +60,87 @@ async def test_required_consumer_failure_fails_execution() -> None:
assert "host-publisher" in result.error.message
+async def test_required_consumer_failure_blocks_attempts_until_unsubscribed() -> None:
+ provider = FauxProvider(provider_id="faux")
+ calls = 0
+
+ async def response(messages, model):
+ nonlocal calls
+ del messages, model
+ calls += 1
+ return AssistantMessage(
+ content=[TextContent(text="done")], stop_reason="end_turn"
+ )
+
+ provider.set_responses([response])
+ agent = Agent(model=provider.model("faux-model"))
+
+ def broken(envelope):
+ del envelope
+ raise RuntimeError("publisher closed")
+
+ unsubscribe = agent.session.subscribe(broken, required=True, name="host-publisher")
+
+ first = await agent.session.execute(
+ PromptExecutionRequest(run_id="run-1", attempt_id="attempt-1", message="hi")
+ )
+ second = await agent.session.execute(
+ PromptExecutionRequest(run_id="run-2", attempt_id="attempt-2", message="hi")
+ )
+
+ assert first.outcome == "failed"
+ assert second.outcome == "failed"
+ assert calls == 0
+
+ unsubscribe()
+ recovered = await agent.session.execute(
+ PromptExecutionRequest(run_id="run-3", attempt_id="attempt-3", message="hi")
+ )
+ assert recovered.outcome == "completed"
+ assert calls == 1
+
+
+async def test_suspension_closes_input_and_cancel_admission_before_delivery() -> None:
+ agent = _agent()
+ receipts = []
+
+ def react_to_suspension(envelope):
+ if envelope.event.type != "agent_suspended":
+ return
+ receipts.append(
+ agent.session.submit_input(
+ InputEnvelope(
+ input_id="late",
+ message=UserMessage(content=[TextContent(text="too late")]),
+ mode="follow_up",
+ )
+ )
+ )
+ agent.session.request_cancel()
+
+ agent.session.subscribe(react_to_suspension)
+ agent._state.last_outcome = "suspended"
+ pending = HitlRequest(
+ question_id="question-1",
+ thread_id="thread-1",
+ payload=ConfirmRequest(prompt="continue?"),
+ created_at=0,
+ )
+ agent.session._active_run_id = "run-1"
+ agent.session._active_attempt_id = "attempt-1"
+ agent.session._accepting_input = True
+ agent.session._accepting_cancel = True
+
+ await agent.session._publish_agent_event(
+ AgentSuspendedEvent(pending_request=pending)
+ )
+
+ assert [receipt.status for receipt in receipts] == ["closed"]
+ assert agent.session._cancel_requested is False
+
+
@pytest.mark.asyncio
async def test_persisted_input_is_committed_before_required_delivery_failure() -> None:
entered = asyncio.Event()