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
"""Edge-case coverage for HITL module — error paths, guard clauses, exhaustion."""
import asyncio
import pytest
from cubeloop.agent.agent import Agent
from cubeloop.agent.types import (
AgentContext,
BeforeToolCallContext,
)
from cubeloop.checkpointer.memory import MemoryCheckpointer
from cubeloop.hitl import (
ApproveAnswer,
HitlError,
HitlNoPendingRequest,
HitlStaleAnswer,
Question,
)
from cubeloop.hitl.channel import InMemoryChannel
from cubeloop.hitl.middleware import ApprovalPolicyMiddleware
from cubeloop.hitl.testing import NoopChannel, ScriptedChannel
from cubeloop.hitl.types import ApproveRequest, HitlRequest
from cubeloop.providers.base import (
AssistantMessage,
TextContent,
ToolCall,
Usage,
)
from cubeloop.providers.faux import FauxProvider, faux_assistant_message
# ── Agent error guards ──────────────────────────────────────────────────────
def _agent(*, channel=None, checkpointer=None, thread_id=None):
provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("done")])
return Agent(
model=provider.model("faux"),
channel=channel,
checkpointer=checkpointer,
thread_id=thread_id,
)
def test_detach_raises_without_channel():
agent = _agent()
with pytest.raises(HitlError, match="agent has no channel bound"):
asyncio.get_event_loop().run_until_complete(agent.detach())
def test_detach_silent_when_nothing_pending():
agent = _agent(channel=InMemoryChannel())
# nothing in-flight — should return without error
asyncio.get_event_loop().run_until_complete(agent.detach())
def test_load_pending_hitl_request_without_checkpointer():
agent = _agent(channel=InMemoryChannel())
result = asyncio.get_event_loop().run_until_complete(
agent.load_pending_hitl_request()
)
assert result is None
def test_load_pending_hitl_request_without_thread_id():
cp = MemoryCheckpointer()
agent = _agent(channel=InMemoryChannel(), checkpointer=cp, thread_id=None)
result = asyncio.get_event_loop().run_until_complete(
agent.load_pending_hitl_request()
)
assert result is None
def test_respond_raises_without_channel():
agent = _agent()
with pytest.raises(HitlError, match="agent has no channel bound"):
asyncio.get_event_loop().run_until_complete(
agent.respond(answer=ApproveAnswer(decision="approve"))
)
def test_respond_raises_without_thread_id():
cp = MemoryCheckpointer()
agent = _agent(channel=InMemoryChannel(), checkpointer=cp)
with pytest.raises(RuntimeError, match="thread_id"):
asyncio.get_event_loop().run_until_complete(
agent.respond(answer=ApproveAnswer(decision="approve"))
)
def test_respond_raises_without_checkpointer():
agent = _agent(channel=InMemoryChannel(), thread_id="t-1")
with pytest.raises(RuntimeError, match="checkpointer"):
asyncio.get_event_loop().run_until_complete(
agent.respond(answer=ApproveAnswer(decision="approve"))
)
def test_respond_raises_when_checkpointer_lacks_hitl():
class _BareCP: # pragma: no cover — minimal stub
async def load(self, tid):
return None
agent = _agent(
channel=InMemoryChannel(),
checkpointer=_BareCP(),
thread_id="t-1",
)
with pytest.raises(HitlError, match="load_pending"):
asyncio.get_event_loop().run_until_complete(
agent.respond(answer=ApproveAnswer(decision="approve"))
)
def test_respond_raises_when_checkpointer_lacks_hitl_answer_store():
class _PartialCP: # pragma: no cover — minimal stub
async def load(self, tid):
return None
async def load_pending(self, tid):
return (
HitlRequest(
question_id="tc-1",
thread_id=tid,
payload=ApproveRequest(
tool_name="bash", tool_call_id="tc-1", args={}
),
created_at=0.0,
),
"R1",
)
agent = _agent(
channel=InMemoryChannel(), checkpointer=_PartialCP(), thread_id="t-1"
)
with pytest.raises(HitlError, match="save_hitl_answer"):
asyncio.get_event_loop().run_until_complete(
agent.respond(answer=ApproveAnswer(decision="approve"))
)
def test_respond_raises_no_pending():
cp = MemoryCheckpointer()
ch = InMemoryChannel()
agent = _agent(channel=ch, checkpointer=cp, thread_id="t-1")
with pytest.raises(HitlNoPendingRequest):
asyncio.get_event_loop().run_until_complete(
agent.respond(answer=ApproveAnswer(decision="approve"))
)
def test_respond_raises_stale_answer():
cp = MemoryCheckpointer()
ch = InMemoryChannel()
req = HitlRequest(
question_id="tc-REAL",
thread_id="t-1",
payload=ApproveRequest(tool_name="bash", tool_call_id="tc-REAL", args={}),
created_at=0.0,
)
asyncio.get_event_loop().run_until_complete(cp.save_pending_request("t-1", req))
agent = _agent(channel=ch, checkpointer=cp, thread_id="t-1")
with pytest.raises(HitlStaleAnswer):
asyncio.get_event_loop().run_until_complete(
agent.respond(
question_id="tc-wrong", answer=ApproveAnswer(decision="approve")
)
)
def test_abort_pending_raises_without_channel():
agent = _agent()
with pytest.raises(HitlError, match="agent has no channel bound"):
asyncio.get_event_loop().run_until_complete(agent.abort_pending("test"))
def test_abort_pending_raises_without_thread_id():
cp = MemoryCheckpointer()
agent = _agent(channel=InMemoryChannel(), checkpointer=cp)
with pytest.raises(RuntimeError, match="thread_id"):
asyncio.get_event_loop().run_until_complete(agent.abort_pending("test"))
def test_abort_pending_raises_without_checkpointer():
agent = _agent(channel=InMemoryChannel(), thread_id="t-1")
with pytest.raises(RuntimeError, match="checkpointer"):
asyncio.get_event_loop().run_until_complete(agent.abort_pending("test"))
def test_abort_pending_cross_process_no_messages():
cp = MemoryCheckpointer()
ch = InMemoryChannel()
agent = _agent(channel=ch, checkpointer=cp, thread_id="t-1")
# No messages at all — should emit AgentAbortedEvent and return.
asyncio.get_event_loop().run_until_complete(
agent.abort_pending("nothing in history")
)
# ── Testing helpers ────────────────────────────────────────────────────────
def test_scripted_channel_exhausted():
ch = ScriptedChannel(answers=[True])
# First call consumes the one answer — succeeds.
asyncio.get_event_loop().run_until_complete(ch.confirm("first"))
# Second call hits exhaustion.
with pytest.raises(HitlError, match="ScriptedChannel exhausted"):
asyncio.get_event_loop().run_until_complete(ch.confirm("exhausted"))
def test_scripted_channel_resume_slot():
ch = ScriptedChannel(answers=[])
ch.attach_resume_answer("tc-r", ApproveAnswer(decision="approve"))
ans = asyncio.get_event_loop().run_until_complete(
ch.approve(tool_name="bash", tool_call_id="tc-r", args={})
)
assert ans.decision == "approve"
def test_noop_channel_ask():
ch = NoopChannel()
answer = asyncio.get_event_loop().run_until_complete(
ch.ask([Question(key="k", prompt="?")])
)
assert answer == {"k": ""}
def test_noop_channel_error_on_unknown_kind():
"""NoopChannel handles approve (ApproveAnswer), confirm (True), ask (dict).
An unknown kind (e.g. a synthetic payload with a made-up kind) triggers
the HitlError guard."""
from cubeloop.hitl.types import ConfirmRequest
ch = NoopChannel()
# ConfirmRequest has kind="confirm", which NoopChannel handles fine.
result = asyncio.get_event_loop().run_until_complete(
ch._await_answer(ConfirmRequest(prompt="ok?"), None, None, "qid")
)
assert result is True
# ── Middleware edge paths ──────────────────────────────────────────────────
def test_args_to_dict_fallback():
from cubeloop.hitl.middleware import _args_to_dict
class _Custom:
def __init__(self):
self.cmd = "ls"
result = _args_to_dict(_Custom())
assert result == {"cmd": "ls"}
async def test_policy_type_error():
ch = InMemoryChannel()
mw = ApprovalPolicyMiddleware(ch, policy=lambda c: 42)
ctx = BeforeToolCallContext(
assistant_message=AssistantMessage(
content=[
TextContent(text=""),
ToolCall(id="tc", name="bash", arguments={}),
],
stop_reason="tool_use",
usage=Usage(),
),
tool_call=ToolCall(id="tc", name="bash", arguments={}),
args={},
context=AgentContext(system_prompt="", messages=[], tools=[]),
)
with pytest.raises(TypeError, match="unexpected"):
await mw.before_tool_call(ctx)
# ── Tools.py edge paths ────────────────────────────────────────────────────
async def test_merge_hitl_details_non_dict_base():
from cubeloop.agent.tools import _merge_hitl_details
result = _merge_hitl_details("plain_string", {"a": 1})
assert result["_non_dict_details"] == "plain_string"
assert result["hitl"] == {"a": 1}
async def test_merge_hitl_details_base_is_none():
from cubeloop.agent.tools import _merge_hitl_details
result = _merge_hitl_details(None, {"x": 1})
assert result == {"hitl": {"x": 1}}
async def test_merge_hitl_details_hitl_is_none():
from cubeloop.agent.tools import _merge_hitl_details
assert _merge_hitl_details(None, None) is None
assert _merge_hitl_details({"a": 1}, None) == {"a": 1}
# ── Channel edge paths ──────────────────────────────────────────────────────
async def test_answer_with_answered_qid_is_noop():
"""answer on a qid that was already resolved doesn't raise — it's idempotent."""
ch = InMemoryChannel()
async def host():
while ch.pending is None:
await asyncio.sleep(0)
await ch.answer(ch.pending.question_id, True)
asyncio.create_task(host())
assert await ch.confirm("ok?") is True
# answering again after resolution won't match — pending is None now
# and a stale answer would raise. We want to verify the current behavior
# is safe (no error for already-resolved).
from cubeloop.hitl import HitlStaleAnswer
with pytest.raises(HitlStaleAnswer):
await ch.answer("any-qid", True) # stale after resolution
async def test_cancel_with_stale_qid_raises():
ch = InMemoryChannel()
async def host():
while ch.pending is None:
await asyncio.sleep(0)
await ch.answer(ch.pending.question_id, True)
asyncio.create_task(host())
await ch.confirm("ok?")
# cancel with a qid that isn't pending → HitlStaleAnswer
from cubeloop.hitl import HitlStaleAnswer
with pytest.raises(HitlStaleAnswer):
await ch.cancel("not-the-qid")
def test_load_pending_hitl_request_with_valid_checkpointer():
"""Cover the return-await-load_pending path in load_pending_hitl_request."""
cp = MemoryCheckpointer()
agent = _agent(channel=InMemoryChannel(), checkpointer=cp, thread_id="t-1")
result = asyncio.get_event_loop().run_until_complete(
agent.load_pending_hitl_request()
)
# No pending data exists — returns None.
assert result is None
def test_load_pending_hitl_request_no_hitl_method():
"""Checkpointer that lacks load_pending_request — graceful None."""
class _NoHITLCp:
async def load(self, tid):
return None
agent = _agent(channel=InMemoryChannel(), checkpointer=_NoHITLCp(), thread_id="t-1")
result = asyncio.get_event_loop().run_until_complete(
agent.load_pending_hitl_request()
)
assert result is None