Enterprise agent platform for building, deploying, and operating AI teammates.
"""Behavior tests for ``task_clarification_draft.py``.
Pure-function coverage (guard order, payload construction, idempotency key
derivation) needs no database at all: every argument
``resolve_publishable_clarification`` takes is an in-memory value the
caller already holds. Four tests are the exceptions, each opening a
private SQLite database the same way the interaction-staging suite does:
the cross-run anchor scenario, which stages a real interaction row through
``interaction_handoff`` to confirm the downstream primitive -- not this
module -- is what degrades a cross-run mismatch; and three payload/legacy-
reader shape comparisons (a ``send_message`` draft, a draft with
interactions, and an empty-form ``ask_user_question`` draft where the two
readers are known to still disagree), which build their drafts through
the real ``draft_from_waiting_request`` and call the real
``get_latest_waiting_question`` against a persisted chat message, rather
than checking this module's own output against itself.
"""
from __future__ import annotations
import logging
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any, Callable
import pytest
from pydantic import ValidationError
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from tests.web.services.task_interaction_schema_shared import (
make_task,
make_trace_event,
make_user,
)
from xagent.core.agent import clarification as clarification_module
from xagent.core.agent.clarification import (
ClarificationDraft,
ClarificationRequestItem,
draft_from_waiting_request,
)
from xagent.core.tools.adapters.vibe.mcp_approval_gate import _gated_interaction_id
from xagent.db.sqlite import apply_sqlite_concurrency_pragmas
from xagent.web.models.database import Base
from xagent.web.models.task import Task
from xagent.web.models.task_interaction import TaskInteractionRequest
from xagent.web.services import ops_signals
from xagent.web.services.chat_history_service import (
get_latest_waiting_question,
persist_assistant_message,
)
from xagent.web.services.task_clarification_draft import (
CLARIFICATION_REQUEST_TTL,
ClarificationResolution,
FailClosed,
NotApplicable,
Publishable,
build_clarification_payload,
clarification_idempotency_key,
parse_clarification_payload,
resolve_publishable_clarification,
)
from xagent.web.services.task_command_transport import COMMAND_ID_PATTERN
from xagent.web.services.task_interaction_service import (
InteractionWritePayloadRejected,
materialize_compatibility_view,
parse_v1_request_payload,
validate_v1_write_payload,
)
from xagent.web.services.task_interaction_staging import (
InteractionAnchor,
interaction_handoff,
stage_interaction_request,
)
from xagent.web.services.task_lease_service import TaskLease
def _now() -> datetime:
return datetime.now(timezone.utc)
def _draft(
*, message: str = "what is your favorite color?", **overrides: Any
) -> ClarificationDraft:
"""Build a :class:`ClarificationDraft` for guard/payload tests that do
not care where a draft came from.
``turn_marker`` is computed with the real ``_compose_turn_marker`` from
whatever ``turn_message_count`` / ``origin_step_id`` / ``requests``
this call ends up with (defaults or overrides), rather than pinned to a
literal string: a hand-written marker can drift from what
``_compose_turn_marker``'s length-prefixed encoding actually produces
(component lengths are on the *filtered* value, not letter-counted by
eye) without any test here noticing.
"""
values: dict[str, Any] = {
"event_id": "11111111-1111-4111-8111-111111111111",
"source": "send_message",
"message": message,
"message_type": "info",
"interactions": (),
"requests": (ClarificationRequestItem("respond", "call-1", "call-1"),),
"origin_step_id": "step-1",
"origin_execution_id": "exec-1",
"turn_message_count": 3,
}
values.update(overrides)
if "turn_marker" not in values:
values["turn_marker"] = clarification_module._compose_turn_marker(
turn_message_count=values["turn_message_count"],
origin_step_id=values["origin_step_id"],
requests=values["requests"],
)
return ClarificationDraft(**values)
def _task(**overrides: Any) -> Task:
values: dict[str, Any] = {
"id": 1,
"runner_id": "runner-a",
"run_id": "run-a",
"lease_attempt_id": "attempt-a",
}
values.update(overrides)
return Task(**values)
def _lease(**overrides: Any) -> TaskLease:
values: dict[str, Any] = {
"task_id": 1,
"runner_id": "runner-a",
"run_id": "run-a",
"attempt_id": "attempt-a",
}
values.update(overrides)
return TaskLease(**values)
def _anchor(**overrides: Any) -> InteractionAnchor:
values: dict[str, Any] = {
"trace_event_id": 42,
"resume_event_id": "resume-event-1",
"resume_execution_id": "resume-exec-1",
"resume_run_partition": "run-a",
}
values.update(overrides)
return InteractionAnchor(**values)
@pytest.fixture(autouse=True)
def _reset_ops_signals():
for name in list(ops_signals.active_degradations()):
ops_signals.clear_degradation(name)
yield
for name in list(ops_signals.active_degradations()):
ops_signals.clear_degradation(name)
# ---------------------------------------------------------------------------
# The four-way pairing between run status and draft presence
# ---------------------------------------------------------------------------
def test_waiting_with_draft_is_publishable() -> None:
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, Publishable)
assert resolution.fail_closed_reason is None
def test_waiting_draft_without_question_event_identity_fails_closed() -> None:
result = {
"status": "waiting_for_user",
"clarification_draft": _draft(event_id=""),
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "missing_event_id"
@pytest.mark.parametrize(
"event_id",
[None, 0, False, [], " id ", "bad/id", "bad\x00id", "a" * 65],
)
def test_invalid_question_event_identity_fails_closed(event_id: Any) -> None:
result = {
"status": "waiting_for_user",
"clarification_draft": _draft(event_id=event_id),
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "invalid_event_id"
def test_waiting_without_draft_fails_closed_as_missing_draft() -> None:
result = {"status": "waiting_for_user"}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "missing_draft"
def test_missing_draft_logs_at_warning_not_error(
caplog: pytest.LogCaptureFixture,
) -> None:
"""This is a degrade-and-proceed path (the caller's non-native handling
of the waiting status is untouched, only the structured row is skipped),
which is why it logs at warning rather than error -- unlike the
non-waiting-with-draft guard just below, which stays at error because it
is only reachable through a caller's own programming mistake. Nothing
in this suite pinned the level before, so a regression back to error
would have passed silently."""
caplog.set_level(
logging.WARNING, logger="xagent.web.services.task_clarification_draft"
)
result = {"status": "waiting_for_user"}
resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
matching = [
record
for record in caplog.records
if "waiting run produced no clarification draft" in record.message
]
assert len(matching) == 1
assert matching[0].levelno == logging.WARNING
def test_non_waiting_with_draft_fails_closed_as_draft_status_mismatch() -> None:
result = {"status": "completed", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "draft_status_mismatch"
def test_non_waiting_without_draft_is_not_applicable() -> None:
result = {"status": "completed"}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, NotApplicable)
assert resolution.reason is None
assert resolution.fail_closed_reason is None
# ---------------------------------------------------------------------------
# The remaining guards, each in isolation
# ---------------------------------------------------------------------------
def test_unfenced_lease_fails_closed() -> None:
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(run_id=None), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "unfenced_lease"
def test_ownership_changed_fails_closed() -> None:
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result,
task=_task(runner_id="someone-else"),
lease=_lease(),
anchor=_anchor(),
now=_now(),
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "ownership_changed"
def test_run_changed_fails_closed() -> None:
"""Same runner, different run: ``task_row_matches_lease_owner`` compares
both ``runner_id`` and ``run_id``, so a runner that moved to a new run
without a matching runner change must fail closed too, not just the
runner-changed half covered by ``test_ownership_changed_fails_closed``
above."""
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result,
task=_task(run_id="a-later-run"),
lease=_lease(),
anchor=_anchor(),
now=_now(),
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "ownership_changed"
def test_attempt_mismatch_fails_closed() -> None:
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result,
task=_task(lease_attempt_id="a-later-attempt"),
lease=_lease(),
anchor=_anchor(),
now=_now(),
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "attempt_mismatch"
def test_guards_run_most_specific_failure_first() -> None:
"""When ownership *and* attempt identity are both wrong on the same
input, the ownership check must win -- it comes first in the guard
sequence because it is the more specific, less data-exposing failure.
A resolver that checked attempt identity before ownership would report
the wrong classification here even though both are genuinely wrong."""
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result,
task=_task(runner_id="someone-else", lease_attempt_id="a-later-attempt"),
lease=_lease(),
anchor=_anchor(),
now=_now(),
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "ownership_changed"
def test_none_attempt_id_fails_closed() -> None:
"""A missing acquisition cannot authorize publishing a question."""
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result,
task=_task(lease_attempt_id="whatever-is-on-the-row"),
lease=_lease(attempt_id=None),
anchor=_anchor(),
now=_now(),
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "attempt_mismatch"
def test_missing_draft_guard_wins_over_unfenced_lease_guard() -> None:
"""Guard 1 (waiting-status vs. draft-presence pairing) must run before
guard 2 (lease fencing). A waiting run with neither a draft nor a
fenced lease has to classify as ``missing_draft`` -- whose caller
contract is "don't discard the round" -- not ``unfenced_lease``, whose
contract is "discard the round wholesale". Swapping the two guards'
order would still return a ``FailClosed`` here, but with the wrong
reason and therefore the wrong consequence for the caller."""
result = {"status": "waiting_for_user"}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(run_id=None), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, FailClosed)
assert resolution.fail_closed_reason == "missing_draft"
def test_missing_anchor_is_not_applicable_not_fail_closed() -> None:
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=None, now=_now()
)
assert isinstance(resolution, NotApplicable)
assert resolution.reason == "no_anchor"
def test_cross_run_anchor_mismatch_still_resolves_as_publishable() -> None:
"""A cross-run anchor is not rejected by this module -- that check was
deliberately moved to ``interaction_handoff``, which owns a dedicated
exception and degradation signal for exactly this mismatch."""
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
result,
task=_task(),
lease=_lease(),
anchor=_anchor(resume_run_partition="a-different-run"),
now=_now(),
)
assert isinstance(resolution, Publishable)
# ---------------------------------------------------------------------------
# The host's MCP approval prompt is never published
# ---------------------------------------------------------------------------
_MIXED_APPROVAL_LOG = (
"an approval prompt shares its waiting turn with another tool's question; "
"neither is published as a structured interaction"
)
def _resolve_with_passing_fence_and_anchor(
draft: ClarificationDraft,
) -> ClarificationResolution:
result = {"status": "waiting_for_user", "clarification_draft": draft}
return resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
def _gated_tool_waiting_draft() -> ClarificationDraft:
gated = _gated_interaction_id("slack", "host-1")
return _draft(
source="tool_waiting",
message_type="question",
requests=(ClarificationRequestItem("mcp_tool", "call-1", gated),),
)
def test_tool_waiting_draft_issued_by_the_approval_gate_is_not_published(
caplog: pytest.LogCaptureFixture,
) -> None:
caplog.set_level(
logging.INFO, logger="xagent.web.services.task_clarification_draft"
)
resolution = _resolve_with_passing_fence_and_anchor(_gated_tool_waiting_draft())
assert resolution == NotApplicable("host_approval_prompt")
assert ops_signals.active_degradations() == {}
assert not [r for r in caplog.records if r.getMessage() == _MIXED_APPROVAL_LOG]
def test_approval_exclusion_runs_after_the_attempt_fence() -> None:
"""A fence failure still discards the round for an approval prompt: the
attempt check runs before the approval exclusion, so a gated draft under
a superseded attempt is ``attempt_mismatch``, not
``host_approval_prompt``."""
result = {
"status": "waiting_for_user",
"clarification_draft": _gated_tool_waiting_draft(),
}
resolution = resolve_publishable_clarification(
result,
task=_task(lease_attempt_id="attempt-current"),
lease=_lease(attempt_id="attempt-stale"),
anchor=_anchor(),
now=_now(),
)
assert resolution == FailClosed("attempt_mismatch")
def test_approval_exclusion_runs_before_the_anchor_check() -> None:
"""An approval prompt with no resume anchor is reported as an approval
prompt, not as ``no_anchor``."""
result = {
"status": "waiting_for_user",
"clarification_draft": _gated_tool_waiting_draft(),
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=None, now=_now()
)
assert resolution == NotApplicable("host_approval_prompt")
def test_multi_tool_draft_with_any_gate_issued_item_is_not_published(
caplog: pytest.LogCaptureFixture,
) -> None:
"""One gate-issued item among several is enough: the whole draft is
published as one row, so publishing it would hand the approval to the
structured-answer path. The other tool's question is therefore not
published either, and an info-level log records the mix."""
caplog.set_level(
logging.INFO, logger="xagent.web.services.task_clarification_draft"
)
gated = _gated_interaction_id("slack", "host-1")
draft = _draft(
source="tool_waiting",
message_type="question",
requests=(
ClarificationRequestItem("mcp_tool", "call-1", gated),
ClarificationRequestItem("other_tool", "call-2", "call-2"),
),
)
resolution = _resolve_with_passing_fence_and_anchor(draft)
assert resolution == NotApplicable("host_approval_prompt")
mixed = [r for r in caplog.records if r.getMessage() == _MIXED_APPROVAL_LOG]
assert len(mixed) == 1, mixed
assert mixed[0].levelno == logging.INFO
assert mixed[0].gated_request_count == 1
assert mixed[0].request_count == 2
def test_tool_waiting_draft_with_no_gate_issued_item_is_publishable() -> None:
draft = _draft(
source="tool_waiting",
message_type="question",
requests=(
ClarificationRequestItem("mcp_tool", "call-1", "call-1"),
ClarificationRequestItem("other_tool", "call-2", "call-2"),
),
)
resolution = _resolve_with_passing_fence_and_anchor(draft)
assert isinstance(resolution, Publishable)
def test_ask_user_question_draft_with_a_gate_shaped_call_id_is_publishable() -> None:
"""The id here is a complete id the gate itself can parse, not merely a
string that starts with the gate prefix, so this pins that the exclusion
applies only to ``tool_waiting`` drafts -- not that a malformed id fails
to parse. An ``ask_user_question`` item's id is the model's tool call
id, and is never treated as an approval prompt."""
gated = _gated_interaction_id("slack", "host-1")
draft = _draft(
source="ask_user_question",
message_type="question",
requests=(ClarificationRequestItem("ask_user_question", gated, gated),),
)
resolution = _resolve_with_passing_fence_and_anchor(draft)
assert isinstance(resolution, Publishable)
# ---------------------------------------------------------------------------
# Payload construction and parsing
# ---------------------------------------------------------------------------
# This builder and task_interaction_service's write-side rules are two
# halves of one contract with no shared type to enforce it: everything this
# builder produces is offered to the write path, so a payload it can build
# that those rules reject is a clarification that can never be published.
# The rows below are the shapes it actually produces, fed through the real
# parser and the real rules rather than through a hand-written mirror.
@pytest.mark.parametrize(
"make_draft",
[
pytest.param(
lambda: _draft(),
id="send_message_draft_carries_no_interactions",
),
pytest.param(
lambda: _draft(
source="ask_user_question",
interactions=(
{
"type": "select_one",
"field": "colour",
"label": "Colour",
"options": [{"label": "Red", "value": "red"}],
},
{"type": "text_input", "field": "why", "label": "Why?"},
),
),
id="ask_user_question_draft_carries_a_form",
),
pytest.param(
lambda: _draft(
source="ask_user_question",
interactions=tuple(
{
"type": "text_input",
"field": f"field_{index}",
"label": "x" * 512,
}
for index in range(400)
),
),
id="oversized_form_is_dropped_to_an_empty_list",
),
],
)
def test_the_clarification_payload_builder_satisfies_the_write_side_rules(
make_draft: Any,
) -> None:
payload = build_clarification_payload(make_draft())
validate_v1_write_payload(parse_v1_request_payload(payload))
def test_an_oversized_clarification_form_really_is_dropped_to_an_empty_list() -> None:
"""The row above named "oversized" only proves something if the builder
actually took its drop branch. Pin that here rather than trusting the
row's id."""
payload = build_clarification_payload(
_draft(
source="ask_user_question",
interactions=tuple(
{"type": "text_input", "field": f"field_{index}", "label": "x" * 512}
for index in range(400)
),
)
)
assert payload["interactions"] == []
assert payload["interactions_dropped"] is True
def test_payload_round_trip_matches_the_legacy_reader_shape_for_a_send_message_draft(
tmp_path: Path,
) -> None:
"""``parse_clarification_payload`` must return the exact shape the real
``get_latest_waiting_question`` (``chat_history_service.py``) returns
for the legacy transcript path -- checked against that real function,
not against this module's own return-type promise.
``send_message`` is the source that actually reaches this comparison
with no interactions: its waiting request never carries an
``"interactions"`` key at all (see the ``send_message`` branch of
``ReActPattern._handle_control_tool`` in ``react.py``), so
``draft_from_waiting_request`` always builds it with an empty
``interactions`` tuple, and the websocket outbound-message path that
persists the matching chat row (``websocket.py``, the
``expect_response`` branch) never passes an ``interactions`` keyword
either, leaving the column ``NULL``. Both readers must call that "no
interactions", i.e. ``None`` -- never ``[]``, which would claim a form
existed when none did.
"""
engine = _engine(tmp_path)
session_factory = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = session_factory()
try:
user_id = make_user(db)
task_id = make_task(db, user_id=user_id)
# No question persisted yet: the legacy reader's "nothing found"
# branch must agree in shape with the parser's "empty payload"
# branch.
no_question = get_latest_waiting_question(db, task_id)
empty_payload_result = parse_clarification_payload({})
assert no_question == (None, None)
assert empty_payload_result == (None, None)
waiting_request = {
"tool_call_id": "call-1",
"tool_name": "send_message",
"message": "what is your favorite color?",
"message_type": "info",
"task_text": "pick a color",
"message_count": 3,
}
draft = draft_from_waiting_request(
waiting_request, execution_id="exec-1", step_id="step-1"
)
assert draft is not None
assert draft.source == "send_message"
assert draft.interactions == ()
persist_assistant_message(
db,
task_id=task_id,
user_id=user_id,
content=draft.message,
message_type="question",
)
real_question, real_interactions = get_latest_waiting_question(db, task_id)
payload = build_clarification_payload(draft)
parsed_question, parsed_interactions = parse_clarification_payload(payload)
assert type(real_question) is type(parsed_question)
assert isinstance(real_question, str) and isinstance(parsed_question, str)
assert real_interactions is None
assert parsed_interactions is None
finally:
db.close()
engine.dispose()
def test_payload_round_trip_matches_the_legacy_reader_shape_for_a_draft_with_interactions(
tmp_path: Path,
) -> None:
"""The ``ask_user_question`` source is the one whose waiting request
always carries a populated ``"interactions"`` key (see the
``ask_user_question`` branch of ``ReActPattern._handle_control_tool``
in ``react.py``), and the websocket outbound-message path persists
that same list into the chat row's ``interactions`` column. Both
readers must return that list back as a list of dicts, not merely
each checked in isolation against a type it is guaranteed to satisfy
by construction."""
engine = _engine(tmp_path)
session_factory = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = session_factory()
try:
user_id = make_user(db)
task_id = make_task(db, user_id=user_id)
interactions = [{"prompt": "pick one"}]
waiting_request = {
"tool_call_id": "call-1",
"tool_name": "ask_user_question",
"message": "pick one",
"message_type": "question",
"interactions": interactions,
"task_text": "pick one",
"message_count": 5,
}
draft = draft_from_waiting_request(
waiting_request, execution_id="exec-1", step_id="step-1"
)
assert draft is not None
assert draft.source == "ask_user_question"
assert draft.interactions == ({"prompt": "pick one"},)
persist_assistant_message(
db,
task_id=task_id,
user_id=user_id,
content=draft.message,
message_type="question",
interactions=interactions,
)
real_question, real_interactions = get_latest_waiting_question(db, task_id)
payload = build_clarification_payload(draft)
parsed_question, parsed_interactions = parse_clarification_payload(payload)
assert type(real_question) is type(parsed_question)
assert type(real_interactions) is type(parsed_interactions)
assert isinstance(real_question, str) and isinstance(parsed_question, str)
assert isinstance(real_interactions, list) and isinstance(
parsed_interactions, list
)
assert all(isinstance(item, dict) for item in real_interactions)
assert all(isinstance(item, dict) for item in parsed_interactions)
assert real_interactions == parsed_interactions == [{"prompt": "pick one"}]
finally:
db.close()
engine.dispose()
def test_payload_round_trip_diverges_from_the_legacy_reader_for_an_empty_form_ask_user_question(
tmp_path: Path,
) -> None:
"""This pins a known, un-reconciled gap between the two readers, not an
ideal contract they are supposed to share.
An empty-form ``ask_user_question`` call is legal: the source is
classified by whether its waiting request carries an ``"interactions"``
key at all, not by whether that key's value is non-empty (see
``draft_from_waiting_request``). Carried through the real path --
``_normalize_ask_user_interactions`` in ``react.py`` turns a missing or
empty ``interactions`` argument into ``[]``, and ``websocket.py``'s
outbound-message handler passes that ``[]`` straight through to
``persist_assistant_message`` because it is a list, not ``None`` -- the
persisted row's ``interactions`` column ends up holding an actual empty
list, not ``NULL``. ``get_latest_waiting_question`` therefore returns
``[]`` for this row. ``parse_clarification_payload`` still normalizes
every empty case to ``None``, so the two readers disagree here: ``[]``
on the legacy side, ``None`` on this module's side. That is today's
actual behavior, asserted as such -- not a bug this test is waiting to
catch.
"""
engine = _engine(tmp_path)
session_factory = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = session_factory()
try:
user_id = make_user(db)
task_id = make_task(db, user_id=user_id)
waiting_request = {
"tool_call_id": "call-1",
"tool_name": "ask_user_question",
"message": "anything else?",
"message_type": "question",
"interactions": [],
"task_text": "anything else?",
"message_count": 5,
}
draft = draft_from_waiting_request(
waiting_request, execution_id="exec-1", step_id="step-1"
)
assert draft is not None
assert draft.source == "ask_user_question"
assert draft.interactions == ()
# Mirrors the real websocket outbound-message path: metadata's
# "interactions" is a list ([]), so it is passed through as [],
# not None -- the persisted column ends up [], not NULL.
persist_assistant_message(
db,
task_id=task_id,
user_id=user_id,
content=draft.message,
message_type="question",
interactions=[],
)
real_question, real_interactions = get_latest_waiting_question(db, task_id)
payload = build_clarification_payload(draft)
parsed_question, parsed_interactions = parse_clarification_payload(payload)
assert isinstance(real_question, str) and isinstance(parsed_question, str)
assert real_interactions == []
assert parsed_interactions is None
finally:
db.close()
engine.dispose()
def test_built_payload_round_trips_through_a_staged_row_and_the_v1_reader(
tmp_path: Path,
) -> None:
"""The pairing this module and ``parse_v1_request_payload``
(``task_interaction_service.py``) both describe in their docstrings --
a builder producing a shape the reader can validate -- had no test
crossing both modules: every existing payload assertion here checks
this module's own dict literal, never a real row read back through the
reader ``materialize_compatibility_view`` actually uses. A key mismatch
between the two (``question`` written, ``message`` required) validated
against an in-memory dict just as cleanly as against a real row, so it
stayed invisible until a persisted row was read back through the
reader for real, which is what this test does.
The anchor below is built directly with :class:`InteractionAnchor`
rather than through the full checkpoint-shaped
``materialize_compatibility_view`` chain (``event_type`` /
``checkpoint_type`` / ``_task_run_id``): ``stage_interaction_request``
only needs an anchor whose ``trace_event_id`` satisfies the foreign key
and does not itself inspect the referenced row's ``data``, so a plain
``make_trace_event`` row is enough. Covering the checkpoint-shaped read
path is a separate concern.
"""
engine = _engine(tmp_path)
session_factory = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = session_factory()
try:
user_id = make_user(db)
task_id = make_task(db, user_id=user_id)
trace_event_id = make_trace_event(db, task_id=task_id)
interactions = (
{"type": "text_input", "field": "color", "label": "Favorite color"},
)
draft = _draft(
message="what is your favorite color?", interactions=interactions
)
payload = build_clarification_payload(draft)
anchor = InteractionAnchor(
trace_event_id=trace_event_id,
resume_event_id="resume-event-1",
resume_execution_id="resume-exec-1",
resume_run_partition="run-a",
)
staged = stage_interaction_request(
db,
task_id=task_id,
run_id=anchor.resume_run_partition,
anchor=anchor,
kind="clarification",
protocol_version=1,
origin="internal",
request_payload=payload,
request_idempotency_key=clarification_idempotency_key(draft),
expires_at=_now() + timedelta(hours=1),
now=_now(),
)
db.commit()
assert staged.created is True
row = db.get(TaskInteractionRequest, staged.staged_db_id)
assert row is not None
parsed = parse_v1_request_payload(row.request_payload)
assert parsed.message == draft.message
assert parsed.interactions is not None
assert len(parsed.interactions) == len(draft.interactions)
finally:
db.close()
engine.dispose()
def test_select_control_payload_round_trips_with_its_options_intact(
tmp_path: Path,
) -> None:
"""A second real shape through the same builder -> stage -> read-back ->
parse round trip as the test above, this time with a ``select_one``
control that carries ``options`` -- the nested-list field none of the
other payload tests exercise end to end. Catches the same class of bug
the ``question``/``message`` key mismatch was: a control field that
looks fine as this module's own dict literal but fails
``AskUserQuestionArgs`` validation once read back for real, because
something about its shape (here, the nested ``InteractionOption`` list)
was never actually round-tripped through the reader.
"""
engine = _engine(tmp_path)
session_factory = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = session_factory()
try:
user_id = make_user(db)
task_id = make_task(db, user_id=user_id)
trace_event_id = make_trace_event(db, task_id=task_id)
interactions = (
{
"type": "select_one",
"field": "color",
"label": "Favorite color",
"options": [
{"label": "Red", "value": "red"},
{"label": "Blue", "value": "blue"},
],
},
)
draft = _draft(
message="what is your favorite color?", interactions=interactions
)
payload = build_clarification_payload(draft)
anchor = InteractionAnchor(
trace_event_id=trace_event_id,
resume_event_id="resume-event-1",
resume_execution_id="resume-exec-1",
resume_run_partition="run-a",
)
staged = stage_interaction_request(
db,
task_id=task_id,
run_id=anchor.resume_run_partition,
anchor=anchor,
kind="clarification",
protocol_version=1,
origin="internal",
request_payload=payload,
request_idempotency_key=clarification_idempotency_key(draft),
expires_at=_now() + timedelta(hours=1),
now=_now(),
)
db.commit()
assert staged.created is True
row = db.get(TaskInteractionRequest, staged.staged_db_id)
assert row is not None
parsed = parse_v1_request_payload(row.request_payload)
assert parsed.message == draft.message
assert parsed.interactions is not None
assert len(parsed.interactions) == 1
control = parsed.interactions[0]
assert control.type == "select_one"
assert control.field == "color"
assert control.label == "Favorite color"
assert control.options is not None
assert [(o.label, o.value) for o in control.options] == [
("Red", "red"),
("Blue", "blue"),
]
finally:
db.close()
engine.dispose()
def test_a_payload_missing_interaction_fields_fails_v1_validation_and_the_materialize_fallback_logs_it(
tmp_path: Path,
caplog: pytest.LogCaptureFixture,
) -> None:
"""Pins the second path to an unreadable payload: a
``request_payload`` written by something other than
``build_clarification_payload`` -- here, one hand-built with an
``interactions`` entry that has only ``field`` and neither of
``InteractionArg``'s two other required fields, ``type`` and
``label`` -- fails ``AskUserQuestionArgs`` validation exactly like the
``question``/``message`` key mismatch this module's other round-trip
tests are pinned against, just via a different malformed shape. Per-
field validation of ``interactions`` entries at the write side is
tracked in #1368; this test only pins today's failure mode at the read
side, not a fix for the write side.
An active row holds this task's answer slot even when its payload
cannot be parsed, so this reports the unanswerable tier rather than
falling back to the legacy transcript -- see
``test_unreadable_payload_is_unanswerable_not_legacy``
(``test_task_interaction_service.py``) for the same assertion pinned
directly against ``materialize_compatibility_view``. This test's own
value is the payload construction path: staged through the real
``stage_interaction_request``, not a bare ORM insert.
The row is staged through the real ``stage_interaction_request``, not
a bare ORM insert: ``request_payload`` is a JSON column with no
``AskUserQuestionArgs``-shape CHECK constraint, so a row this shape can
reach the table for real, the same way
``test_t1_falls_back_to_legacy_when_request_payload_does_not_parse``
(``test_task_interaction_service.py``) already established for a
differently-malformed payload.
"""
malformed_payload = {
"message": "what is your favorite color?",
"interactions": [{"field": "color"}],
}
with pytest.raises(ValidationError):
parse_v1_request_payload(malformed_payload)
engine = _engine(tmp_path)
session_factory = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = session_factory()
try:
user_id = make_user(db)
task_id = make_task(db, user_id=user_id)
trace_event_id = make_trace_event(db, task_id=task_id)
anchor = InteractionAnchor(
trace_event_id=trace_event_id,
resume_event_id="resume-event-1",
resume_execution_id="resume-exec-1",
resume_run_partition="run-a",
)
draft = _draft()
staged = stage_interaction_request(
db,
task_id=task_id,
run_id=anchor.resume_run_partition,
anchor=anchor,
kind="clarification",
protocol_version=1,
origin="internal",
request_payload=malformed_payload,
request_idempotency_key=clarification_idempotency_key(draft),
expires_at=_now() + timedelta(hours=1),
now=_now(),
)
assert staged.created is True
# _active_native_row_criteria() joins on
# TaskInteractionRequest.run_id == Task.run_id; make_task() leaves
# a task's run_id NULL, which the staged row above (run_id="run-a")
# would never match, so materialize_compatibility_view would take
# the earlier "no active row" exit instead of reaching the
# payload-parse guard this test targets.
task = db.get(Task, task_id)
assert task is not None
task.run_id = anchor.resume_run_partition
db.commit()
caplog.set_level(
logging.WARNING, logger="xagent.web.services.task_interaction_service"
)
view = materialize_compatibility_view(db, task_id)
assert view.tier == "unanswerable"
assert view.question is None
assert view.interactions is None
assert view.reason == "payload_unreadable"
matching = [
record
for record in caplog.records
if "failed v1 payload validation" in record.message
]
assert len(matching) == 1
assert matching[0].levelno == logging.WARNING
finally:
db.close()
engine.dispose()
def test_idempotency_key_matches_the_command_id_pattern() -> None:
draft = _draft()
key = clarification_idempotency_key(draft)
assert COMMAND_ID_PATTERN.fullmatch(key) is not None
assert key == draft.event_id
def test_question_event_identity_is_carried_in_the_v1_payload() -> None:
draft = _draft()
assert build_clarification_payload(draft)["event_id"] == draft.event_id
def test_idempotency_key_changes_with_question_event_identity() -> None:
base = _draft(event_id="11111111-1111-4111-8111-111111111111")
changed = _draft(event_id="22222222-2222-4222-8222-222222222222")
assert clarification_idempotency_key(base) != clarification_idempotency_key(changed)
def test_idempotency_key_ignores_message_content() -> None:
"""Changing payload content cannot rename the published question."""
base = _draft(message="short")
changed = _draft(message="a completely different, much longer question")
assert clarification_idempotency_key(base) == clarification_idempotency_key(changed)
def test_idempotency_key_ignores_source() -> None:
"""The question event identity stays authoritative across draft sources."""
base = _draft(source="send_message")
changed = _draft(source="ask_user_question")
assert clarification_idempotency_key(base) == clarification_idempotency_key(changed)
def test_idempotency_key_ignores_origin_execution_id() -> None:
"""Execution bookkeeping cannot create a second question identity."""
base = _draft(origin_execution_id="exec-1")
changed = _draft(origin_execution_id="exec-2")
assert clarification_idempotency_key(base) == clarification_idempotency_key(changed)
def test_oversized_question_is_truncated_and_the_idempotency_key_is_unaffected() -> (
None
):
long_question = "q" * (32 * 1024)
draft = _draft(message=long_question)
payload = build_clarification_payload(draft)
assert payload["message_truncated"] is True
assert len(payload["message"].encode("utf-8")) <= 16 * 1024
assert payload["message"] != long_question
key_before = clarification_idempotency_key(draft)
truncated_variant = _draft(message=long_question[: len(long_question) // 2])
key_after = clarification_idempotency_key(truncated_variant)
assert key_before == key_after
def test_oversized_multi_byte_question_truncates_on_a_character_boundary() -> None:
"""Every character here encodes to 3 UTF-8 bytes, so a byte-slice that
ignores character boundaries would land mid-character. ``errors="ignore"``
in ``_truncate_to_byte_limit`` drops a partial trailing character rather
than raising, but nothing pinned that the result stays valid UTF-8 with
no stray replacement character -- this test is that pin."""
long_question = "你" * (10 * 1024) # ~30 KiB, over the 16 KiB limit
draft = _draft(message=long_question)
payload = build_clarification_payload(draft)
assert payload["message_truncated"] is True
encoded = payload["message"].encode("utf-8")
assert len(encoded) <= 16 * 1024
# Round-trips cleanly and introduces no U+FFFD replacement character --
# a mid-character byte slice would either raise here or leave one.
assert encoded.decode("utf-8") == payload["message"]
assert "�" not in payload["message"]
def test_oversized_interactions_are_dropped_entirely() -> None:
huge_interactions = tuple({"field": "x" * 2000, "index": i} for i in range(64))
draft = _draft(interactions=huge_interactions)
payload = build_clarification_payload(draft)
assert payload["interactions_dropped"] is True
assert payload["interactions"] == []
assert payload["message"] == draft.message
def test_request_leaf_control_characters_are_stripped_from_the_payload() -> None:
"""``requests`` is built from ``ClarificationRequestItem.to_dict()``,
whose string fields (``tool_name``, ``tool_call_id``,
``interaction_id``) come from the same untrusted tool-call surface as
``interactions``' free-text leaves and must go through the same
``_clean_leaves`` filter, not straight into the payload."""
dirty_requests = (
ClarificationRequestItem("tool\x07one", "call\x00-1", "call\x00-1"),
)
draft = _draft(requests=dirty_requests)
payload = build_clarification_payload(draft)
assert payload["requests"] == [
{
"tool_name": "toolone",
"tool_call_id": "call-1",
"interaction_id": "call-1",
}
]
# Filtering payload leaves must not move the event-derived identity.
key_before = clarification_idempotency_key(draft)
build_clarification_payload(draft)
assert clarification_idempotency_key(draft) == key_before
def test_message_type_control_characters_are_stripped_from_the_payload() -> None:
"""``message_type`` reaches ``ClarificationDraft`` by way of
``react.py``'s ``send_message`` handler --
``str(args.get("message_type", "info"))``, a raw LLM tool-call
argument with no runtime validation against the tool schema's declared
``enum``. A JSON-schema ``enum`` is a hint the model is told to follow,
not a constraint this code enforces, so ``message_type`` needs the
same control-character filtering ``question`` already gets, not a
straight pass-through."""
draft = _draft(message_type="info\x07\x00BEL-AND-NUL")
payload = build_clarification_payload(draft)
assert payload["message_type"] == "infoBEL-AND-NUL"
# Filtering message_type must not move the event-derived identity.
key_before = clarification_idempotency_key(draft)
build_clarification_payload(draft)
assert clarification_idempotency_key(draft) == key_before
def test_interaction_leaf_control_characters_are_stripped_through_full_payload_assembly() -> (
None
):
"""``test_character_domain_matches_the_marker_cleaning_domain`` pins
``_strip_control_characters`` in isolation; this pins the same
filtering as it actually runs inside ``build_clarification_payload``
for a form's ``interactions`` leaves."""
dirty_interactions = ({"prompt": "pick\x07one", "id": "opt\x00-1"},)
draft = _draft(interactions=dirty_interactions)
payload = build_clarification_payload(draft)
assert payload["interactions"] == [{"prompt": "pickone", "id": "opt-1"}]
def _message_draft(raw: str) -> ClarificationDraft:
return _draft(
source="ask_user_question",
message=raw,
interactions=({"type": "text_input", "field": "f", "label": "L"},),
)
def _field_draft(raw: str) -> ClarificationDraft:
return _draft(
source="ask_user_question",
message="Which one?",
interactions=({"type": "text_input", "field": raw, "label": "L"},),
)
def _produced_message(payload: dict[str, Any]) -> Any:
return payload["message"]
def _produced_field(payload: dict[str, Any]) -> Any:
return payload["interactions"][0]["field"]
# The producer must emit every ``field`` already in the form the write-side
# rules compare it against. A control character next to an edge space is the
# case that used to slip through: the control-character filter drops the
# control character and leaves the space behind, which the write-side trim
# table then refuses. ``message`` is only filtered, never trimmed: the write
# side only refuses a blank message, so its edge whitespace is kept. The inner
# cases pin that whitespace between two visible characters survives on both
# leaves.
@pytest.mark.parametrize(
("build", "extract", "raw", "expected"),
[
pytest.param(
_message_draft, _produced_message, "\x07 ab", " ab", id="message-leading"
),
pytest.param(
_message_draft, _produced_message, "ab \x07", "ab ", id="message-trailing"
),
pytest.param(
_message_draft,
_produced_message,
"a \x07 b",
"a b",
id="message-inner-negative-control",
),
pytest.param(
_field_draft, _produced_field, "\x07 ab", "ab", id="field-leading"
),
pytest.param(
_field_draft, _produced_field, "ab \x07", "ab", id="field-trailing"
),
pytest.param(
_field_draft,
_produced_field,
"a \x07 b",
"a b",
id="field-inner-negative-control",
),
],
)
def test_producer_side_normalizes_field_edges_and_keeps_message_edges(
build: Callable[[str], ClarificationDraft],
extract: Callable[[dict[str, Any]], Any],
raw: str,
expected: str,
) -> None:
payload = build_clarification_payload(build(raw))
assert extract(payload) == expected
validate_v1_write_payload(parse_v1_request_payload(payload))
def test_message_leading_indentation_and_newlines_are_kept() -> None:
"""A message that opens with a newline and an indented code line keeps
both: trimming them would change what the user sees and make the
structured message differ from the legacy transcript."""
raw = "\n print('hi')\n"
resolution = _resolve_with_passing_fence_and_anchor(_message_draft(raw))
assert isinstance(resolution, Publishable)
assert resolution.request_payload["message"] == raw
def test_bom_only_question_is_not_applicable_after_normalization(
caplog: pytest.LogCaptureFixture,
) -> None:
"""Only a message made entirely of trim-table characters that include
U+FEFF used to reach the write side as ``message_blank``: Python's
``str.strip()`` does not remove U+FEFF, so the resolver's own blank
check let it through as publishable. The resolver now judges blankness
with the write side's trim function, so such a message lands on the
existing ``empty_question`` outcome instead. U+FEFF is not a control
character, so the "empty after removing control characters" warning
must not fire."""
caplog.set_level(
logging.WARNING, logger="xagent.web.services.task_clarification_draft"
)
result = {
"status": "waiting_for_user",
"clarification_draft": _draft(message="\ufeff"),
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert resolution == NotApplicable("empty_question")
assert not [
record
for record in caplog.records
if record.message
== "clarification question was empty after removing control characters"
]
def test_option_label_and_value_made_only_of_control_characters_are_refused() -> None:
"""Option ``label`` / ``value`` are deliberately not normalized, so an
option that is blank after control-character filtering is still refused
by the write side, exactly as before."""
draft = _draft(
source="ask_user_question",
interactions=(
{
"type": "select_one",
"field": "seat",
"label": "Seat",
"options": [{"label": "\x07\x07", "value": "\x01"}],
},
),
)
payload = build_clarification_payload(draft)
assert payload["interactions"][0]["options"][0] == {"label": "", "value": ""}
with pytest.raises(InteractionWritePayloadRejected) as exc:
validate_v1_write_payload(parse_v1_request_payload(payload))
assert exc.value.refusal.rule == "option_blank"
def test_option_edge_whitespace_is_left_untouched() -> None:
"""Edge whitespace on an option ``label`` / ``value`` is valid today and
is shown to the user as written; the producer must not trim it."""
draft = _draft(
source="ask_user_question",
interactions=(
{
"type": "select_one",
"field": "seat",
"label": "Seat",
"options": [{"label": " 靠窗 ", "value": " 靠窗 "}],
},
),
)
payload = build_clarification_payload(draft)
option = payload["interactions"][0]["options"][0]
assert option["label"] == " 靠窗 "
assert option["value"] == " 靠窗 "
def test_payload_still_too_large_after_truncation_is_not_applicable(
caplog: pytest.LogCaptureFixture,
) -> None:
"""Only ``tool_waiting`` -- the multi-tool waiting point -- can
realistically produce thousands of ``requests`` entries;
``send_message`` and ``ask_user_question`` always contribute exactly
one (see ``ClarificationDraft.requests``'s docstring), so a
``send_message`` draft with 6000 requests is not a shape production
can ever hand this function.
Also pins the level of ``build_clarification_payload``'s
still-oversized-after-truncation log at warning, the same degrade-
and-proceed reasoning as ``test_missing_draft_logs_at_warning_not_error``
above: this guard lets the round proceed as ``NotApplicable`` rather
than failing it, so a regression to error would misclassify a routine
degradation as a fault.
"""
caplog.set_level(
logging.WARNING, logger="xagent.web.services.task_clarification_draft"
)
many_requests = tuple(
ClarificationRequestItem(f"tool-{i}", f"call-{i}", f"call-{i}")
for i in range(6000)
)
draft = _draft(source="tool_waiting", requests=many_requests)
result = {"status": "waiting_for_user", "clarification_draft": draft}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, NotApplicable)
assert resolution.reason == "payload_too_large"
matching = [
record
for record in caplog.records
if "exceeded the maximum size even after truncation" in record.message
]
assert len(matching) == 1
assert matching[0].levelno == logging.WARNING
def test_question_emptied_by_character_filtering_is_not_applicable(
caplog: pytest.LogCaptureFixture,
) -> None:
"""Also pins the level of ``build_clarification_payload``'s
empty-after-filtering log at warning, the same degrade-and-proceed
reasoning as ``test_missing_draft_logs_at_warning_not_error`` above:
this guard lets the round proceed as ``NotApplicable`` rather than
failing it, so a regression to error would misclassify a routine
degradation as a fault.
"""
caplog.set_level(
logging.WARNING, logger="xagent.web.services.task_clarification_draft"
)
draft = _draft(message="\x00\x01\x02\x1f")
result = {"status": "waiting_for_user", "clarification_draft": draft}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, NotApplicable)
assert resolution.reason == "empty_question"
matching = [
record
for record in caplog.records
if "empty after removing control characters" in record.message
]
assert len(matching) == 1
assert matching[0].levelno == logging.WARNING
def test_whitespace_only_question_is_not_applicable() -> None:
"""A question made only of whitespace -- including a tab -- survives
``_strip_control_characters`` unchanged, since ``\\n``, ``\\r``, and
``\\t`` are the three exceptions that filter keeps. The guard must
still treat it as empty rather than let a blank question through as
``Publishable``."""
draft = _draft(message=" \t \n ")
result = {"status": "waiting_for_user", "clarification_draft": draft}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, NotApplicable)
assert resolution.reason == "empty_question"
def test_character_domain_matches_the_marker_cleaning_domain() -> None:
"""This module's own character filter and
``clarification.py``'s marker-cleaning filter cannot share code (the
core layer never imports the web layer), so both copies must agree on
every probe string here or the two have silently drifted apart."""
from xagent.web.services.task_clarification_draft import (
_strip_control_characters,
)
probes = [
"plain text",
"line one\nline two",
"tab\tseparated",
"carriage\rreturn",
"null\x00byte",
"unit separator\x1f",
"bell\x07character",
"",
]
for probe in probes:
assert _strip_control_characters(probe) == clarification_module._marker_clean(
probe
), probe
def test_expires_at_is_now_plus_the_ttl_constant() -> None:
result = {"status": "waiting_for_user", "clarification_draft": _draft()}
now = _now()
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=now
)
assert isinstance(resolution, Publishable)
assert resolution.expires_at == now + CLARIFICATION_REQUEST_TTL
# ---------------------------------------------------------------------------
# The multiple-drafts degradation signal
# ---------------------------------------------------------------------------
def test_single_waiting_step_does_not_register_the_multiple_drafts_signal() -> None:
result = {
"status": "waiting_for_user",
"clarification_draft": _draft(),
"clarification_superseded_step_ids": [],
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, Publishable)
assert (
ops_signals.CLARIFICATION_MULTIPLE_DRAFTS
not in ops_signals.active_degradations()
)
def test_superseded_steps_register_the_multiple_drafts_signal_and_it_stays_up() -> None:
"""Registering the signal is not undone by the very publish that
reports it: a successful publish this round does not erase the fact
that a sibling step's draft was discarded this round, so the signal
must still be registered once ``resolve_publishable_clarification``
returns."""
result = {
"status": "waiting_for_user",
"clarification_draft": _draft(),
"clarification_superseded_step_ids": ["step-2"],
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, Publishable)
assert (
ops_signals.CLARIFICATION_MULTIPLE_DRAFTS in ops_signals.active_degradations()
)
def test_interrupted_winner_with_superseded_steps_registers_the_multiple_drafts_signal() -> (
None
):
"""When an interrupt wins a wakeup that also superseded a losing
waiting step, ``AgentExecutionAdapter`` puts
``clarification_superseded_step_ids`` on the *interrupted* result, not
a waiting one (see the ``"interrupted"`` branch of
``AgentExecutionAdapter._normalize_result`` in ``execution_adapter.py``).
The signal has to register here even though the guard sequence
classifies this round ``NotApplicable(None)`` well before it would
otherwise touch ``clarification_superseded_step_ids`` -- registering
must not be gated behind reaching the ``Publishable`` path."""
result = {
"status": "interrupted",
"clarification_superseded_step_ids": ["step-2"],
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, NotApplicable)
assert resolution.reason is None
assert (
ops_signals.CLARIFICATION_MULTIPLE_DRAFTS in ops_signals.active_degradations()
)
def test_waiting_with_superseded_steps_and_no_anchor_registers_the_multiple_drafts_signal() -> (
None
):
"""Same point as the interrupted-winner case above, for the other
degrade-not-fail exit: a waiting round with no resume anchor still
reports a sibling step having been superseded, even though it never
reaches the ``Publishable`` branch that used to be the only place this
registered."""
result = {
"status": "waiting_for_user",
"clarification_draft": _draft(),
"clarification_superseded_step_ids": ["step-2"],
}
resolution = resolve_publishable_clarification(
result, task=_task(), lease=_lease(), anchor=None, now=_now()
)
assert isinstance(resolution, NotApplicable)
assert resolution.reason == "no_anchor"
assert (
ops_signals.CLARIFICATION_MULTIPLE_DRAFTS in ops_signals.active_degradations()
)
def test_missing_draft_registers_and_a_later_publish_clears_it() -> None:
missing_result = {"status": "waiting_for_user"}
resolve_publishable_clarification(
missing_result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert ops_signals.CLARIFICATION_DRAFT_MISSING in ops_signals.active_degradations()
clean_result = {"status": "waiting_for_user", "clarification_draft": _draft()}
resolution = resolve_publishable_clarification(
clean_result, task=_task(), lease=_lease(), anchor=_anchor(), now=_now()
)
assert isinstance(resolution, Publishable)
assert (
ops_signals.CLARIFICATION_DRAFT_MISSING not in ops_signals.active_degradations()
)
# ---------------------------------------------------------------------------
# Cross-run anchor: this module lets it through; the staging primitive
# downstream is what actually degrades it.
# ---------------------------------------------------------------------------
def _engine(tmp_path: Path):
db_path = tmp_path / "clarification_draft.db"
engine = create_engine(f"sqlite:///{db_path}")
apply_sqlite_concurrency_pragmas(engine)
Base.metadata.create_all(bind=engine)
return engine
def test_cross_run_anchor_mismatch_degrades_downstream_in_the_staging_primitive(
tmp_path: Path,
) -> None:
engine = _engine(tmp_path)
session_factory = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = session_factory()
try:
user_id = make_user(db)
task_id = make_task(db, user_id=user_id)
anchor_trace_event_id = make_trace_event(db, task_id=task_id)
task = db.get(Task, task_id)
task.runner_id = "runner-a"
task.run_id = "run-a"
task.lease_attempt_id = "attempt-a"
db.flush([task])
lease = TaskLease(
task_id=task_id,
runner_id="runner-a",
run_id="run-a",
attempt_id="attempt-a",
)
draft = _draft()
result = {"status": "waiting_for_user", "clarification_draft": draft}
mismatched_anchor = _anchor(
trace_event_id=anchor_trace_event_id, resume_run_partition="a-different-run"
)
resolution = resolve_publishable_clarification(
result, task=task, lease=lease, anchor=mismatched_anchor, now=_now()
)
assert isinstance(resolution, Publishable)
with interaction_handoff(
db, lease, task=task, anchor=mismatched_anchor, now=_now()
) as handoff:
handoff.stage(
kind="clarification",
protocol_version=1,
request_payload=resolution.request_payload,
request_idempotency_key=resolution.request_idempotency_key,
expires_at=resolution.expires_at,
)
db.rollback()
assert (
ops_signals.INTERACTION_RUN_PARTITION_MISMATCH_DEGRADED
in ops_signals.active_degradations()
)
assert (
ops_signals.INTERACTION_HANDOFF_DEGRADED
not in ops_signals.active_degradations()
)
finally:
db.close()
engine.dispose()