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
import asyncio
import pytest
from cubeloop.agent.agent import Agent, _MessageQueue
from cubeloop.agent.types import AgentTool
from cubeloop.middleware.base import Middleware
from cubeloop.providers.base import (
AssistantMessage,
Model,
ReasoningControl,
TextContent,
UserMessage,
)
from cubeloop.providers.faux import FauxProvider, faux_assistant_message
from pydantic import BaseModel
def make_model() -> Model:
return Model(id="faux-1", provider_id="faux")
class TestAgentInit:
def test_agent_unwraps_bound_model(self):
provider = FauxProvider(provider_id="faux")
bound_model = provider.model("faux-1")
agent = Agent(model=bound_model)
assert agent.state.model.id == "faux-1"
assert agent.state.model.provider_id == "faux"
def test_default_state(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
assert agent.state.system_prompt == ""
assert agent.state.reasoning == ReasoningControl()
assert agent.state.tools == []
assert agent.state.messages == []
assert agent.state.is_streaming is False
assert agent.state.streaming_message is None
assert agent.state.pending_tool_calls == set()
assert agent.state.error_message is None
assert agent._checkpoint_loaded is False
def test_custom_initial_state(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(
model=provider.model("faux-1"),
system_prompt="You are a helpful assistant.",
reasoning=ReasoningControl(mode="on", effort="low"),
)
assert agent.state.system_prompt == "You are a helpful assistant."
assert agent.state.reasoning == ReasoningControl(mode="on", effort="low")
def test_middleware_tools_are_registered_on_agent(self):
class Params(BaseModel):
pass
async def execute(tool_call_id, params, *, signal=None, on_update=None):
return None
tool = AgentTool(
name="from_middleware",
description="middleware tool",
parameters=Params,
execute=execute,
)
class ToolMiddleware(Middleware):
tools = [tool]
agent = Agent(
model=FauxProvider(provider_id="faux").model("faux-1"),
middleware=[ToolMiddleware()],
)
assert agent.state.tools == [tool]
class TestAgentSubscribe:
def test_subscribe_and_unsubscribe(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
count = 0
def listener(event, signal=None):
nonlocal count
count += 1
unsub = agent.subscribe(listener)
assert count == 0
unsub()
async def test_events_emitted_on_prompt(self):
provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("ok")])
agent = Agent(model=provider.model("faux-1"))
events = []
agent.subscribe(lambda e, s=None: events.append(e.type))
await agent.prompt("hello")
assert "agent_start" in events
assert "message_start" in events
assert "message_end" in events
assert "agent_end" in events
async def test_full_lifecycle_events_for_thrown_run_failures(self):
async def bad_stream(*args, **kwargs):
raise RuntimeError("provider exploded")
provider = FauxProvider(provider_id="faux")
provider.stream = bad_stream
agent = Agent(model=provider.model("faux-1"))
events = []
agent.subscribe(lambda e, s=None: events.append(e.type))
await agent.prompt("hello")
assert events == [
"agent_start",
"turn_start",
"message_start",
"message_end",
"message_start",
"message_end",
"turn_end",
"agent_end",
]
last_msg = agent.state.messages[-1]
assert last_msg.role == "assistant"
assert last_msg.stop_reason == "error"
assert last_msg.error_message == "provider exploded"
assert agent.state.error_message == "provider exploded"
async def test_await_async_subscribers_before_prompt_resolves(self):
provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("ok")])
agent = Agent(model=provider.model("faux-1"))
barrier = asyncio.Event()
listener_finished = False
async def listener(event, signal=None):
nonlocal listener_finished
if event.type == "agent_end":
await barrier.wait()
listener_finished = True
agent.subscribe(listener)
prompt_resolved = False
async def run_prompt():
nonlocal prompt_resolved
await agent.prompt("hello")
prompt_resolved = True
task = asyncio.create_task(run_prompt())
await asyncio.sleep(0.05)
assert not prompt_resolved
assert not listener_finished
assert agent.state.is_streaming is True
barrier.set()
await task
assert listener_finished
assert prompt_resolved
assert agent.state.is_streaming is False
class TestAgentState:
def test_tools_are_copied(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
tools = [
AgentTool(
name="t",
description="t",
parameters=type(
"P", (object,), {"model_json_schema": classmethod(lambda cls: {})}
),
execute=lambda *a, **k: None,
)
]
agent.state.tools = tools
assert agent.state.tools is not tools
def test_messages_are_copied(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
messages = [UserMessage(content=[TextContent(text="hi")])]
agent.state.messages = messages
assert agent.state.messages is not messages
class TestAgentQueues:
def test_steer_queues_message(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
msg = UserMessage(content=[TextContent(text="steering")])
agent.steer(msg)
assert msg not in agent.state.messages
def test_follow_up_queues_message(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
msg = UserMessage(content=[TextContent(text="follow-up")])
agent.follow_up(msg)
assert msg not in agent.state.messages
class TestAgentAbort:
def test_abort_without_active_run_does_not_throw(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
agent.abort()
class TestAgentPromptGuards:
async def test_raises_when_prompt_called_while_streaming(self):
barrier = asyncio.Event()
provider = FauxProvider(provider_id="faux")
async def slow_stream(*args, **kwargs):
from cubeloop.providers.base import MessageStream, StreamEvent
ms = MessageStream()
async def produce():
await barrier.wait()
msg = faux_assistant_message("ok")
ms.push(StreamEvent(type="done"))
ms.set_result(msg)
asyncio.create_task(produce())
return ms
provider.stream = slow_stream
agent = Agent(model=provider.model("faux-1"))
task = asyncio.create_task(agent.prompt("first"))
await asyncio.sleep(0.02)
assert agent.state.is_streaming is True
try:
await agent.prompt("second")
assert False, "Should have raised"
except RuntimeError as e:
assert "already processing" in str(e).lower()
barrier.set()
await task
async def test_raises_when_resume_called_while_streaming(self):
barrier = asyncio.Event()
provider = FauxProvider(provider_id="faux")
async def slow_stream(*args, **kwargs):
from cubeloop.providers.base import MessageStream, StreamEvent
ms = MessageStream()
async def produce():
await barrier.wait()
msg = faux_assistant_message("ok")
ms.push(StreamEvent(type="done"))
ms.set_result(msg)
asyncio.create_task(produce())
return ms
provider.stream = slow_stream
agent = Agent(model=provider.model("faux-1"))
task = asyncio.create_task(agent.prompt("first"))
await asyncio.sleep(0.02)
try:
await agent.resume()
assert False, "Should have raised"
except RuntimeError as e:
assert "already processing" in str(e).lower()
barrier.set()
await task
class TestAgentResume:
async def test_resume_processes_follow_up_messages(self):
provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message("Initial response"),
faux_assistant_message("Processed"),
]
)
agent = Agent(model=provider.model("faux-1"))
await agent.prompt("Initial")
agent.follow_up(UserMessage(content=[TextContent(text="follow-up")]))
await agent.resume()
has_follow_up = any(
isinstance(m, UserMessage)
and any(
isinstance(c, TextContent) and c.text == "follow-up" for c in m.content
)
for m in agent.state.messages
)
assert has_follow_up
assert isinstance(agent.state.messages[-1], AssistantMessage)
async def test_resume_drains_steering_queue_before_follow_up(self):
"""resume() should drain the steering queue first when the last
message is from the assistant."""
provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message("Initial"),
faux_assistant_message("Steered"),
]
)
agent = Agent(model=provider.model("faux-1"))
await agent.prompt("hello")
agent.steer(UserMessage(content=[TextContent(text="steer-msg")]))
await agent.resume()
has_steer = any(
isinstance(m, UserMessage)
and any(
isinstance(c, TextContent) and c.text == "steer-msg" for c in m.content
)
for m in agent.state.messages
)
assert has_steer
assert isinstance(agent.state.messages[-1], AssistantMessage)
async def test_resume_raises_on_assistant_last_with_empty_queues(self):
"""resume() raises RuntimeError when the last message is from the
assistant and both steering and follow-up queues are empty."""
provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("done")])
agent = Agent(model=provider.model("faux-1"))
await agent.prompt("hello")
with pytest.raises(RuntimeError, match="Cannot continue from message role"):
await agent.resume()
class TestMessageQueueAllMode:
def test_drain_returns_all_messages_at_once(self):
q = _MessageQueue(mode="all")
m1 = UserMessage(content=[TextContent(text="a")])
m2 = UserMessage(content=[TextContent(text="b")])
m3 = UserMessage(content=[TextContent(text="c")])
q.enqueue(m1)
q.enqueue(m2)
q.enqueue(m3)
drained = q.drain()
assert drained == [m1, m2, m3]
assert not q.has_items()
def test_drain_returns_empty_when_no_items(self):
q = _MessageQueue(mode="all")
assert q.drain() == []
def test_has_items_reflects_state(self):
q = _MessageQueue(mode="all")
assert not q.has_items()
q.enqueue(UserMessage(content=[TextContent(text="x")]))
assert q.has_items()
def test_clear_removes_all(self):
q = _MessageQueue(mode="all")
q.enqueue(UserMessage(content=[TextContent(text="a")]))
q.enqueue(UserMessage(content=[TextContent(text="b")]))
q.clear()
assert not q.has_items()
assert q.drain() == []
class TestAgentStatePendingToolCalls:
def test_setter_makes_a_copy(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
original = {"call-1", "call-2"}
agent.state.pending_tool_calls = original
retrieved = agent.state.pending_tool_calls
assert retrieved == {"call-1", "call-2"}
# Must be a distinct set, not the same object
assert retrieved is not original
class TestAgentReset:
async def test_reset_clears_state_after_prompt(self):
provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("response")])
agent = Agent(model=provider.model("faux-1"))
await agent.prompt("hello")
assert len(agent.state.messages) > 0
agent._checkpoint_loaded = True
agent.reset()
assert agent.state.messages == []
assert agent.state.is_streaming is False
assert agent.state.streaming_message is None
assert agent.state.pending_tool_calls == set()
assert agent.state.error_message is None
async def test_reset_clears_queues(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
agent.steer(UserMessage(content=[TextContent(text="steer")]))
agent.follow_up(UserMessage(content=[TextContent(text="follow")]))
agent.reset()
# After reset, queues should be empty — drain returns nothing
assert agent._steering_queue.drain() == []
assert agent._follow_up_queue.drain() == []
async def test_reset_clears_session_input_receipts(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
agent.session._input_status["input-1"] = "committed"
agent.session._input_durability["input-1"] = "memory"
agent.reset()
assert agent.session._input_status == {}
assert agent.session._input_durability == {}
assert agent.session._queued_inputs == {}
class TestAgentAbortSignal:
async def test_abort_sets_signal_during_active_run(self):
barrier = asyncio.Event()
provider = FauxProvider(provider_id="faux")
async def slow_stream(*args, **kwargs):
from cubeloop.providers.base import MessageStream, StreamEvent
ms = MessageStream()
async def produce():
await barrier.wait()
msg = faux_assistant_message("ok")
ms.push(StreamEvent(type="done"))
ms.set_result(msg)
asyncio.create_task(produce())
return ms
provider.stream = slow_stream
agent = Agent(model=provider.model("faux-1"))
task = asyncio.create_task(agent.prompt("hello"))
await asyncio.sleep(0.02)
assert agent._active_signal is not None
assert not agent._active_signal.is_set()
agent.abort()
assert agent._active_signal.is_set()
barrier.set()
await task
class TestAgentWaitForIdle:
async def test_returns_immediately_when_no_active_run(self):
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model("faux-1"))
# No active run, _active_done is None — should return immediately
await agent.wait_for_idle()
async def test_waits_until_prompt_completes(self):
barrier = asyncio.Event()
provider = FauxProvider(provider_id="faux")
async def slow_stream(*args, **kwargs):
from cubeloop.providers.base import MessageStream, StreamEvent
ms = MessageStream()
async def produce():
await barrier.wait()
msg = faux_assistant_message("ok")
ms.push(StreamEvent(type="done"))
ms.set_result(msg)
asyncio.create_task(produce())
return ms
provider.stream = slow_stream
agent = Agent(model=provider.model("faux-1"))
prompt_task = asyncio.create_task(agent.prompt("hello"))
await asyncio.sleep(0.02)
idle_resolved = False
async def wait():
nonlocal idle_resolved
await agent.wait_for_idle()
idle_resolved = True
wait_task = asyncio.create_task(wait())
await asyncio.sleep(0.02)
assert not idle_resolved
barrier.set()
await prompt_task
await wait_task
assert idle_resolved
class TestAgentPromptInputTypes:
async def test_prompt_with_message_object(self):
provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("response")])
agent = Agent(model=provider.model("faux-1"))
msg = UserMessage(content=[TextContent(text="direct message")])
await agent.prompt(msg)
has_direct = any(
isinstance(m, UserMessage)
and any(
isinstance(c, TextContent) and c.text == "direct message"
for c in m.content
)
for m in agent.state.messages
)
assert has_direct
assert isinstance(agent.state.messages[-1], AssistantMessage)
async def test_prompt_with_list_of_messages(self):
provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("response")])
agent = Agent(model=provider.model("faux-1"))
msgs = [
UserMessage(content=[TextContent(text="first")]),
UserMessage(content=[TextContent(text="second")]),
]
await agent.prompt(msgs)
texts = [
c.text
for m in agent.state.messages
if isinstance(m, UserMessage)
for c in m.content
if isinstance(c, TextContent)
]
assert "first" in texts
assert "second" in texts
assert isinstance(agent.state.messages[-1], AssistantMessage)
def _steer_msg(text: str, steer_id: str) -> UserMessage:
return UserMessage(
content=[TextContent(text=text)], metadata={"steer_id": steer_id}
)
def test_message_queue_remove_by_steer_id():
q = _MessageQueue(mode="all")
q.enqueue(_steer_msg("a", "s1"))
q.enqueue(_steer_msg("b", "s2"))
assert q.remove("s1") is True
assert [m.content[0].text for m in q.drain()] == ["b"]
def test_message_queue_remove_missing_returns_false():
q = _MessageQueue(mode="all")
q.enqueue(_steer_msg("a", "s1"))
assert q.remove("nope") is False
assert len(q.drain()) == 1
def test_message_queue_remove_ignores_messages_without_steer_id():
q = _MessageQueue(mode="all")
q.enqueue(UserMessage(content=[TextContent(text="x")])) # no metadata.steer_id
assert q.remove("s1") is False
@pytest.mark.asyncio
async def test_agent_cancel_steer_removes_queued_steer():
agent = Agent(model=FauxProvider(provider_id="faux").model("faux-1"))
agent.steer(_steer_msg("hi", "s1"))
assert agent.cancel_steer("s1") is True
assert agent.cancel_steer("s1") is False