Enterprise agent platform for building, deploying, and operating AI teammates.
"""External-scope MESSAGE commands: routing, registration, and the boundary.
The seam under test lets an embedding application execute external task
input through the durable command transport. Every test drives one edge:
the dispatcher adapter routes an external-scope MESSAGE to the registered
executor and nothing else, a deferral crosses the adapter untouched so the
transport's defer budget (not the failure budget) absorbs lease contention,
a deployment without a registered core refuses terminally, a scoped command
never runs the first-party chat core, and a client frame cannot mint a
scoped command at the WebSocket enqueue boundary.
"""
from datetime import UTC, datetime, timedelta
from types import SimpleNamespace
from typing import Any
import pytest
from xagent.web.api import websocket as websocket_api
from xagent.web.models.agent import Agent
from xagent.web.models.task import Task, TaskStatus
from xagent.web.models.task_command import TaskExecutionCommand
from xagent.web.models.task_command_terminal_event import TaskCommandTerminalEvent
from xagent.web.services import task_command_execution as command_execution_service
from xagent.web.services import task_execution as task_execution_service
from xagent.web.services.external_task_input import (
EXTERNAL_INPUT_NOT_APPLIED_MESSAGE,
EXTERNAL_INPUT_UNCONFIRMED_MESSAGE,
execute_external_task_input_command,
register_external_task_input_executor,
registered_external_task_input_executor,
unregister_external_task_input_executor,
)
from xagent.web.services.task_command_transport import (
COMMAND_COMPLETED,
COMMAND_FAILED,
COMMAND_PENDING,
MAX_COMMAND_DEFERS,
MAX_COMMAND_FAILURES,
ClaimedTaskCommand,
TaskCommandDeferred,
TaskCommandKind,
TaskCommandRejected,
dispatch_one_task_command,
enqueue_task_command,
max_command_defers,
)
from xagent.web.services.task_execution_controller import TaskControlState
from .conftest import _admin_headers, _direct_db_session, client
pytestmark = pytest.mark.usefixtures("_test_db")
@pytest.fixture(autouse=True)
def _clean_executor_registry():
unregister_external_task_input_executor()
yield
unregister_external_task_input_executor()
def _claimed_message_command(
*,
task_id: int = 101,
payload: dict[str, Any],
command_id: str = "ext-input-1",
defer_count: int = 0,
) -> ClaimedTaskCommand:
return ClaimedTaskCommand(
id=1,
task_id=task_id,
actor_user_id=None,
command_id=command_id,
kind=TaskCommandKind.MESSAGE,
payload=payload,
target_run_id=None,
attempt_count=1,
defer_count=defer_count,
)
def _create_agent() -> tuple[int, int]:
headers = _admin_headers()
response = client.post(
"/api/agents",
headers=headers,
json={
"name": "External input agent",
"description": "External input test agent",
"instructions": "You are an external input test agent.",
"execution_mode": "balanced",
},
)
assert response.status_code == 200, response.text
agent_id = int(response.json()["id"])
db = _direct_db_session()
try:
owner_user_id = int(db.query(Agent).filter(Agent.id == agent_id).one().user_id)
finally:
db.close()
return agent_id, owner_user_id
def _create_waiting_task(*, agent_id: int, owner_user_id: int) -> int:
db = _direct_db_session()
try:
task = Task(
user_id=owner_user_id,
title="external input task",
status=TaskStatus.WAITING_FOR_USER,
control_state=TaskControlState.RUNNING.value,
run_id="run-external",
state_version=4,
agent_id=agent_id,
source="external",
is_visible=False,
)
db.add(task)
db.commit()
db.refresh(task)
return int(task.id)
finally:
db.close()
def _forbid_first_party_chat(monkeypatch: pytest.MonkeyPatch) -> None:
async def _fail(*_args: Any, **_kwargs: Any) -> None:
raise AssertionError(
"the first-party chat core must not run for a scoped MESSAGE"
)
monkeypatch.setattr(command_execution_service, "handle_task_message", _fail)
# ---------------------------------------------------------------------------
# Registration semantics
# ---------------------------------------------------------------------------
def test_registering_the_same_executor_twice_is_a_no_op() -> None:
async def executor(_command: ClaimedTaskCommand) -> None:
return None
register_external_task_input_executor(executor)
register_external_task_input_executor(executor)
assert registered_external_task_input_executor() is executor
def test_registering_a_different_executor_is_refused() -> None:
async def first(_command: ClaimedTaskCommand) -> None:
return None
async def second(_command: ClaimedTaskCommand) -> None:
return None
register_external_task_input_executor(first)
with pytest.raises(ValueError, match="already registered"):
register_external_task_input_executor(second)
assert registered_external_task_input_executor() is first
def test_unregister_returns_the_executor_and_frees_the_slot() -> None:
async def first(_command: ClaimedTaskCommand) -> None:
return None
async def second(_command: ClaimedTaskCommand) -> None:
return None
register_external_task_input_executor(first)
assert unregister_external_task_input_executor() is first
register_external_task_input_executor(second)
assert registered_external_task_input_executor() is second
def test_a_non_callable_executor_is_refused() -> None:
with pytest.raises(TypeError, match="callable"):
register_external_task_input_executor("not-callable") # type: ignore[arg-type]
assert registered_external_task_input_executor() is None
# ---------------------------------------------------------------------------
# Dispatcher adapter routing
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_external_scope_message_routes_to_the_registered_executor(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""The adapter hands the claimed command to the seam verbatim.
The actor load, origin resolution, and delivery-ledger probes of the
first-party arm belong to first-party rows; none of them may run for an
external-scope command, so the routing must happen before all of them
(``actor_user_id=None`` would otherwise fail the actor load).
"""
_forbid_first_party_chat(monkeypatch)
observed: list[ClaimedTaskCommand] = []
async def executor(command: ClaimedTaskCommand) -> dict[str, Any]:
observed.append(command)
return {"delivered": True}
register_external_task_input_executor(executor)
command = _claimed_message_command(
payload={"scope": "external", "message": "the answer"}
)
result = await command_execution_service._execute_durable_task_command(command)
assert observed == [command]
assert result == {"delivered": True}
@pytest.mark.asyncio
async def test_external_scope_message_deferral_crosses_the_adapter(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""A deferral must reach the dispatcher as ``TaskCommandDeferred``.
That exception type is what routes the disposition to the defer budget
instead of the failure budget; wrapping or swallowing it would consume
terminal failure attempts on a condition that clears by itself.
"""
_forbid_first_party_chat(monkeypatch)
async def executor(_command: ClaimedTaskCommand) -> None:
raise TaskCommandDeferred("the parked run still holds the resume lease")
register_external_task_input_executor(executor)
command = _claimed_message_command(
payload={"scope": "external", "message": "the answer"}
)
with pytest.raises(TaskCommandDeferred, match="resume lease"):
await command_execution_service._execute_durable_task_command(command)
@pytest.mark.asyncio
async def test_external_scope_message_without_a_registered_core_is_terminal(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""No registered core means no retry can succeed: reject, don't defer.
An indefinitely PENDING command would also block every later command
for the same task behind the per-task FIFO.
"""
_forbid_first_party_chat(monkeypatch)
command = _claimed_message_command(
payload={"scope": "external", "message": "the answer"}
)
with pytest.raises(TaskCommandRejected, match="no external input execution core"):
await command_execution_service._execute_durable_task_command(command)
@pytest.mark.asyncio
async def test_foreign_scope_message_is_rejected_terminally(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""A scope naming no execution core must not run the first-party core."""
_forbid_first_party_chat(monkeypatch)
async def executor(_command: ClaimedTaskCommand) -> None:
raise AssertionError("the external core must not run for a foreign scope")
register_external_task_input_executor(executor)
for scope_value in ("workforce", {"nested": "dict"}):
command = _claimed_message_command(
payload={"scope": scope_value, "message": "x"}
)
with pytest.raises(TaskCommandRejected, match="has no execution core"):
await command_execution_service._execute_durable_task_command(command)
@pytest.mark.asyncio
async def test_scopeless_message_stays_on_the_first_party_path(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""The pre-external payload shape keeps its first-party execution core."""
async def seam_must_not_run(_command: ClaimedTaskCommand) -> None:
raise AssertionError("the external seam must not run for a scopeless MESSAGE")
register_external_task_input_executor(seam_must_not_run)
first_party_calls: list[int] = []
async def record_chat(_ws: Any, task_id: int, _data: dict[str, Any]) -> None:
first_party_calls.append(task_id)
monkeypatch.setattr(command_execution_service, "handle_task_message", record_chat)
monkeypatch.setattr(
command_execution_service,
"_load_command_actor",
lambda _actor_id: SimpleNamespace(id=7, is_admin=False),
)
monkeypatch.setattr(
command_execution_service,
"_load_command_message_delivery_status",
lambda _task_id, _turn_id: "dispatched",
)
command = ClaimedTaskCommand(
id=1,
task_id=55,
actor_user_id=7,
command_id="chat-1",
kind=TaskCommandKind.MESSAGE,
payload={"message": "hello"},
target_run_id=None,
attempt_count=1,
)
result = await command_execution_service._execute_durable_task_command(command)
assert first_party_calls == [55]
assert result == {"task_id": 55, "command_id": "chat-1", "kind": "message"}
# ---------------------------------------------------------------------------
# The seam itself
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_seam_rejects_with_unsupported_scope_reason_when_unregistered() -> None:
command = _claimed_message_command(payload={"scope": "external", "message": "x"})
with pytest.raises(TaskCommandRejected) as excinfo:
await execute_external_task_input_command(command)
assert excinfo.value.reason == "unsupported_scope"
# ---------------------------------------------------------------------------
# First-party WebSocket enqueue boundary
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_client_frames_cannot_name_a_command_scope() -> None:
"""``scope`` is server-owned: a client frame carrying it is refused.
Without this boundary a first-party chat frame could route its MESSAGE
command into the external execution core with a forged identity payload.
Loud rejection rather than a silent strip, so the sender learns the
frame was not accepted as written.
"""
for kind in (
TaskCommandKind.MESSAGE,
TaskCommandKind.PAUSE,
TaskCommandKind.RESUME,
):
with pytest.raises(
task_execution_service.ClientVisibleValidationError, match="scope"
):
await websocket_api._enqueue_websocket_task_command(
task_id=1,
message_data={
"user": SimpleNamespace(id=7, is_admin=False),
"message": "hello",
"scope": "external",
},
kind=kind,
command_id="forged-1",
)
# ---------------------------------------------------------------------------
# End to end through the durable transport
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_deferred_external_input_spends_the_defer_budget_not_failures() -> None:
"""Contention defers durably and the retry converges on one delivery.
This is the transport chain an embedding application relies on: enqueue
while the parked run holds the resume lease, observe a defer (status
back to PENDING, ``defer_count`` up, ``failure_count`` untouched), then
complete on the next claim once the lease is free.
"""
agent_id, owner_user_id = _create_agent()
task_id = _create_waiting_task(agent_id=agent_id, owner_user_id=owner_user_id)
attempts: list[int] = []
async def executor(command: ClaimedTaskCommand) -> dict[str, Any]:
attempts.append(command.attempt_count)
if len(attempts) == 1:
raise TaskCommandDeferred("the parked run still holds the resume lease")
return {"delivered": True}
register_external_task_input_executor(executor)
db = _direct_db_session()
try:
enqueued = enqueue_task_command(
db,
task_id=task_id,
actor_user_id=owner_user_id,
command_id="ext-input-e2e",
kind=TaskCommandKind.MESSAGE,
payload={"scope": "external", "message": "the answer"},
)
assert enqueued.created
finally:
db.close()
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-e2e")
.one()
)
assert row.status == COMMAND_PENDING
assert int(row.defer_count or 0) == 1
assert int(row.failure_count or 0) == 0
# The defer backoff parks the claim briefly; expire it so the second
# dispatch below can claim without sleeping through real time.
row.claim_expires_at = datetime.now(UTC) - timedelta(seconds=1)
db.commit()
finally:
db.close()
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-e2e")
.one()
)
assert row.status == COMMAND_COMPLETED
assert row.result == {"delivered": True}
assert int(row.failure_count or 0) == 0
finally:
db.close()
assert attempts == [1, 2]
@pytest.mark.asyncio
async def test_exhausted_external_deferral_withholds_command_identity(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""An external audience never sees durable command identity.
The terminal rebind in ``execute_durable_task_command`` runs *after* the
executor's own draft, so the disclosure decision has to live in
``_terminal_command_event_draft`` itself: an exhausted external-scope
deferral must persist ``include_command_identity=False`` (same policy as
the external cancel) while still carrying the exception's own
``resend_safe`` evidence. The live ``agent_error`` frame follows the
same rule: identity withheld and a purpose-built terminal sentence,
pinned here because the exhausted-deferral path broadcasts through the
same chokepoint.
"""
from unittest.mock import AsyncMock, MagicMock
agent_id, owner_user_id = _create_agent()
task_id = _create_waiting_task(agent_id=agent_id, owner_user_id=owner_user_id)
async def executor(_command: ClaimedTaskCommand) -> dict[str, Any]:
raise TaskCommandDeferred(
"the parked run still holds the resume lease",
resend_safe=True,
)
register_external_task_input_executor(executor)
broadcast_manager = MagicMock()
broadcast_manager.broadcast_to_task = AsyncMock()
monkeypatch.setattr(websocket_api, "manager", broadcast_manager)
db = _direct_db_session()
try:
enqueued = enqueue_task_command(
db,
task_id=task_id,
actor_user_id=owner_user_id,
command_id="ext-input-exhausted",
kind=TaskCommandKind.MESSAGE,
payload={"scope": "external", "message": "the answer"},
)
assert enqueued.created
# Spend all but the last unit of the defer budget so the next
# deferral is the terminal one -- max_command_defers() real round
# trips would prove nothing more about the disposition under test.
db.query(TaskExecutionCommand).filter(
TaskExecutionCommand.command_id == "ext-input-exhausted"
).update(
{TaskExecutionCommand.defer_count: max_command_defers() - 1},
synchronize_session=False,
)
db.commit()
finally:
db.close()
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
payloads = [
call.args[0] for call in broadcast_manager.broadcast_to_task.await_args_list
]
assert [payload["type"] for payload in payloads] == ["agent_error"]
(exhausted_payload,) = payloads
assert exhausted_payload["message"] == EXTERNAL_INPUT_NOT_APPLIED_MESSAGE
assert "command_id" not in exhausted_payload
assert "command_kind" not in exhausted_payload
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-exhausted")
.one()
)
assert row.status == COMMAND_FAILED
event = (
db.query(TaskCommandTerminalEvent)
.filter(TaskCommandTerminalEvent.task_command_id == int(row.id))
.one()
)
assert event.outcome == "failed"
assert event.message_code == "task_command_deferred"
assert event.resend_safe is True
assert event.include_command_identity is False
finally:
db.close()
@pytest.mark.asyncio
async def test_defer_exhaustion_boundary_uses_the_effective_budget(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Both budget consumers must use the effective budget, not the constant.
With a raised TTL the budget is 2*TTL, so the historical constant's
boundary (defer count 60) must stay non-terminal: the wrapper must not
broadcast and the transport must keep the row PENDING. At the effective
boundary the command terminalizes -- and because an exhausted
``resend_safe=False`` deferral proves nothing about the downstream
handoff, the broadcast must assert only uncertainty, never
non-application.
"""
from unittest.mock import AsyncMock, MagicMock
monkeypatch.setenv("XAGENT_TASK_LEASE_TTL_SECONDS", "300")
budget = max_command_defers()
assert budget == 600
agent_id, owner_user_id = _create_agent()
task_id = _create_waiting_task(agent_id=agent_id, owner_user_id=owner_user_id)
async def executor(_command: ClaimedTaskCommand) -> dict[str, Any]:
raise TaskCommandDeferred("the delivery handoff is still pending")
register_external_task_input_executor(executor)
broadcast_manager = MagicMock()
broadcast_manager.broadcast_to_task = AsyncMock()
monkeypatch.setattr(websocket_api, "manager", broadcast_manager)
def seed_defer_count(count: int) -> None:
# The command's own claim_expires_at, not a next-attempt column --
# this transport has none -- gates whether a PENDING row is
# claimable (``_claim_availability_predicate``). The first seed
# relies on the fresh row's NULL default; the second clears the
# one-second backoff the prior deferral armed so the row is
# claimable again without sleeping through real time.
db = _direct_db_session()
try:
db.query(TaskExecutionCommand).filter(
TaskExecutionCommand.command_id == "ext-input-boundary"
).update(
{
TaskExecutionCommand.defer_count: count,
TaskExecutionCommand.claim_expires_at: None,
},
synchronize_session=False,
)
db.commit()
finally:
db.close()
db = _direct_db_session()
try:
enqueued = enqueue_task_command(
db,
task_id=task_id,
actor_user_id=owner_user_id,
command_id="ext-input-boundary",
kind=TaskCommandKind.MESSAGE,
payload={"scope": "external", "message": "the answer"},
)
assert enqueued.created
finally:
db.close()
# The historical constant's boundary: one deferral past count 59 must
# spend budget, not terminalize.
seed_defer_count(MAX_COMMAND_DEFERS - 1)
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
broadcast_manager.broadcast_to_task.assert_not_awaited()
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-boundary")
.one()
)
assert row.status == COMMAND_PENDING
assert int(row.defer_count or 0) == MAX_COMMAND_DEFERS
assert (
db.query(TaskCommandTerminalEvent)
.filter(TaskCommandTerminalEvent.task_command_id == int(row.id))
.count()
== 0
)
finally:
db.close()
# The effective boundary: the six-hundredth deferral is terminal, and
# its broadcast asserts only uncertainty.
seed_defer_count(budget - 1)
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
payloads = [
call.args[0] for call in broadcast_manager.broadcast_to_task.await_args_list
]
assert [payload["type"] for payload in payloads] == ["agent_error"]
(exhausted_payload,) = payloads
assert exhausted_payload["message"] == EXTERNAL_INPUT_UNCONFIRMED_MESSAGE
assert "command_id" not in exhausted_payload
assert "command_kind" not in exhausted_payload
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-boundary")
.one()
)
assert row.status == COMMAND_FAILED
event = (
db.query(TaskCommandTerminalEvent)
.filter(TaskCommandTerminalEvent.task_command_id == int(row.id))
.one()
)
assert event.outcome == "failed"
assert event.resend_safe is False
finally:
db.close()
@pytest.mark.asyncio
async def test_exhausted_generic_failure_reports_an_unconfirmed_outcome(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""A generic failure proves nothing about the downstream handoff.
The failure-budget exhaustion arm broadcasts through the same external
branch; a worker may have injected the answer before the exception, so
the audience must get the uncertainty sentence, never categorical
non-application.
"""
from unittest.mock import AsyncMock, MagicMock
agent_id, owner_user_id = _create_agent()
task_id = _create_waiting_task(agent_id=agent_id, owner_user_id=owner_user_id)
async def executor(_command: ClaimedTaskCommand) -> dict[str, Any]:
raise RuntimeError("the runtime broke mid-delivery")
register_external_task_input_executor(executor)
broadcast_manager = MagicMock()
broadcast_manager.broadcast_to_task = AsyncMock()
monkeypatch.setattr(websocket_api, "manager", broadcast_manager)
db = _direct_db_session()
try:
enqueued = enqueue_task_command(
db,
task_id=task_id,
actor_user_id=owner_user_id,
command_id="ext-input-generic-failure",
kind=TaskCommandKind.MESSAGE,
payload={"scope": "external", "message": "the answer"},
)
assert enqueued.created
db.query(TaskExecutionCommand).filter(
TaskExecutionCommand.command_id == "ext-input-generic-failure"
).update(
{TaskExecutionCommand.failure_count: MAX_COMMAND_FAILURES - 1},
synchronize_session=False,
)
db.commit()
finally:
db.close()
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
payloads = [
call.args[0] for call in broadcast_manager.broadcast_to_task.await_args_list
]
assert [payload["type"] for payload in payloads] == ["agent_error"]
(failure_payload,) = payloads
assert failure_payload["message"] == EXTERNAL_INPUT_UNCONFIRMED_MESSAGE
assert "command_id" not in failure_payload
assert "command_kind" not in failure_payload
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-generic-failure")
.one()
)
assert row.status == COMMAND_FAILED
finally:
db.close()
@pytest.mark.asyncio
async def test_rejected_external_input_broadcasts_and_keeps_the_bound_draft(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""A terminal rejection must surface, and the executor's draft must win.
The seam executor is the one MESSAGE handler with no notification
channel of its own: without the broadcast, a deferred answer that is
later terminally rejected vanishes silently while the task stays parked
(xorbitsai/xagent-saas#952 B2). And the rejection disposition must
persist the draft the executor bound -- hardcoding a neutral one
silently discarded its identity-withholding (#952 M3) -- proven here
through the real dispatch path, not by reading back the attribute.
The bound draft uses ``message_code=None`` rather than the more obvious
``TASK_COMMAND_FAILED``: the fallback ``_terminal_command_event_draft``
derives exactly ``task_command_failed``/``resend_safe=False``/identity
withheld for this exact command (a rejection on an external-scope
MESSAGE), so a fallback-equivalent bound value would pass even if
precedence were broken and the fallback ran instead. ``None`` is a value
``TerminalTaskEventDraft`` accepts but the fallback never produces, so
only the bound draft winning can explain the assertion below.
"""
from unittest.mock import AsyncMock, MagicMock
from xagent.web.services.task_command_terminal_events import (
TerminalTaskEventDraft,
bind_terminal_event_draft,
)
agent_id, owner_user_id = _create_agent()
task_id = _create_waiting_task(agent_id=agent_id, owner_user_id=owner_user_id)
async def executor(_command: ClaimedTaskCommand) -> dict[str, Any]:
rejection = TaskCommandRejected(
"the continuation was refused", reason="continuation_refused"
)
bind_terminal_event_draft(
rejection,
TerminalTaskEventDraft(
message_code=None,
resend_safe=False,
include_command_identity=False,
),
)
raise rejection
register_external_task_input_executor(executor)
broadcast_manager = MagicMock()
broadcast_manager.broadcast_to_task = AsyncMock()
monkeypatch.setattr(websocket_api, "manager", broadcast_manager)
db = _direct_db_session()
try:
enqueued = enqueue_task_command(
db,
task_id=task_id,
actor_user_id=owner_user_id,
command_id="ext-input-rejected",
kind=TaskCommandKind.MESSAGE,
payload={"scope": "external", "message": "the answer"},
)
assert enqueued.created
finally:
db.close()
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
payloads = [
call.args[0] for call in broadcast_manager.broadcast_to_task.await_args_list
]
assert [payload["type"] for payload in payloads] == ["agent_error"]
(rejection_payload,) = payloads
# The live frame mirrors the persisted-event disclosure rule: the
# external audience never sees durable command identity, and the generic
# fallback's "Please try again." would be false for the non-retryable
# rejections this broadcast exists to surface.
assert rejection_payload["message"] == EXTERNAL_INPUT_NOT_APPLIED_MESSAGE
assert "command_id" not in rejection_payload
assert "command_kind" not in rejection_payload
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-rejected")
.one()
)
assert row.status == COMMAND_FAILED
event = (
db.query(TaskCommandTerminalEvent)
.filter(TaskCommandTerminalEvent.task_command_id == int(row.id))
.one()
)
assert event.outcome == "failed"
assert event.message_code is None
assert event.include_command_identity is False
finally:
db.close()
@pytest.mark.asyncio
async def test_rejected_external_input_without_a_bound_draft_gets_the_fallback(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""An executor that binds nothing still gets a classified terminal event.
The rejection arm derives the standard draft only when the executor
bound none, so the fallback must classify the outcome
(``task_command_failed``) and withhold identity for the external scope
-- the other half of the precedence contract pinned above.
"""
from unittest.mock import AsyncMock, MagicMock
agent_id, owner_user_id = _create_agent()
task_id = _create_waiting_task(agent_id=agent_id, owner_user_id=owner_user_id)
async def executor(_command: ClaimedTaskCommand) -> dict[str, Any]:
raise TaskCommandRejected(
"the continuation was refused", reason="continuation_refused"
)
register_external_task_input_executor(executor)
broadcast_manager = MagicMock()
broadcast_manager.broadcast_to_task = AsyncMock()
monkeypatch.setattr(websocket_api, "manager", broadcast_manager)
db = _direct_db_session()
try:
enqueued = enqueue_task_command(
db,
task_id=task_id,
actor_user_id=owner_user_id,
command_id="ext-input-rejected-unbound",
kind=TaskCommandKind.MESSAGE,
payload={"scope": "external", "message": "the answer"},
)
assert enqueued.created
finally:
db.close()
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
payloads = [
call.args[0] for call in broadcast_manager.broadcast_to_task.await_args_list
]
assert [payload["type"] for payload in payloads] == ["agent_error"]
(rejection_payload,) = payloads
assert rejection_payload["message"] == EXTERNAL_INPUT_NOT_APPLIED_MESSAGE
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-rejected-unbound")
.one()
)
assert row.status == COMMAND_FAILED
event = (
db.query(TaskCommandTerminalEvent)
.filter(TaskCommandTerminalEvent.task_command_id == int(row.id))
.one()
)
assert event.outcome == "failed"
assert event.message_code == "task_command_failed"
assert event.include_command_identity is False
finally:
db.close()
@pytest.mark.asyncio
async def test_rejection_broadcast_failure_does_not_supersede_the_disposition(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""A failed broadcast must not turn a terminal rejection into a retry.
``broadcast_to_task`` re-raises non-connection errors (its control-state
snapshot read can fail), and an exception escaping the rejection arm
would supersede ``TaskCommandRejected``: the dispatcher's generic
disposition would then spend the failure budget on a command whose
outcome is already durably decided, and the executor-bound draft would
be lost with it. The broadcast is fire-and-forget for the disposition:
one dispatch must leave the command terminally failed with the bound
draft persisted.
"""
from unittest.mock import AsyncMock, MagicMock
from xagent.web.services.task_command_terminal_events import (
TerminalTaskEventDraft,
bind_terminal_event_draft,
)
agent_id, owner_user_id = _create_agent()
task_id = _create_waiting_task(agent_id=agent_id, owner_user_id=owner_user_id)
async def executor(_command: ClaimedTaskCommand) -> dict[str, Any]:
rejection = TaskCommandRejected(
"the continuation was refused", reason="continuation_refused"
)
bind_terminal_event_draft(
rejection,
TerminalTaskEventDraft(
message_code=None,
resend_safe=False,
include_command_identity=False,
),
)
raise rejection
register_external_task_input_executor(executor)
broadcast_manager = MagicMock()
broadcast_manager.broadcast_to_task = AsyncMock(
side_effect=Exception("the control-state snapshot read failed")
)
monkeypatch.setattr(websocket_api, "manager", broadcast_manager)
db = _direct_db_session()
try:
enqueued = enqueue_task_command(
db,
task_id=task_id,
actor_user_id=owner_user_id,
command_id="ext-input-broadcast-broke",
kind=TaskCommandKind.MESSAGE,
payload={"scope": "external", "message": "the answer"},
)
assert enqueued.created
finally:
db.close()
processed = await dispatch_one_task_command(
command_execution_service.execute_durable_task_command
)
assert processed is True
broadcast_manager.broadcast_to_task.assert_awaited()
db = _direct_db_session()
try:
row = (
db.query(TaskExecutionCommand)
.filter(TaskExecutionCommand.command_id == "ext-input-broadcast-broke")
.one()
)
assert row.status == COMMAND_FAILED
event = (
db.query(TaskCommandTerminalEvent)
.filter(TaskCommandTerminalEvent.task_command_id == int(row.id))
.one()
)
assert event.outcome == "failed"
assert event.message_code is None
assert event.include_command_identity is False
finally:
db.close()