Enterprise agent platform for building, deploying, and operating AI teammates.
"""Startup configuration parsing and fail-fast validation.
Covers env parsing, startup validation, and vocabulary pairings, plus
``Task.source`` normalization -- the current no-strip/no-lower spec.
"""
from __future__ import annotations
import dataclasses
import logging
import re
import pytest
import xagent.config as config
import xagent.web.services.interaction_rollout as ir
from xagent.web.models.task_interaction import (
INTERACTION_ORIGIN_VOCABULARY,
TASK_SOURCE_LITERALS,
TaskInteractionRequest,
normalize_interaction_origin,
)
@pytest.fixture(autouse=True)
def _clean_state(monkeypatch):
monkeypatch.delenv(config.INTERACTION_PROTOCOL_MODE, raising=False)
monkeypatch.delenv(config.INTERACTION_NATIVE_SOURCES, raising=False)
monkeypatch.setattr(ir, "_policy", None)
ir._counters.clear()
yield
monkeypatch.setattr(ir, "_policy", None)
ir._counters.clear()
# ---------------------------------------------------------------------------
# T-C: config parsing + startup validation
# ---------------------------------------------------------------------------
def test_tc1_defaults_to_legacy_with_empty_sources_and_version_1():
policy = ir.validate_interaction_rollout_at_startup()
assert policy.mode == "legacy"
assert policy.native_sources == frozenset()
assert policy.native_protocol_version == 1
@pytest.mark.parametrize(
"raw,expected",
[("legacy", "legacy"), (" READ ", "read"), ("Native", "native")],
)
def test_tc2_valid_modes_parse_with_whitespace_and_case(monkeypatch, raw, expected):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, raw)
if expected == "native":
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, "sdk")
policy = ir.validate_interaction_rollout_at_startup()
assert policy.mode == expected
def test_tc3_invalid_mode_raises_with_original_value_and_legal_values(monkeypatch):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "prod")
with pytest.raises(ir.InteractionRolloutConfigError) as exc:
ir.validate_interaction_rollout_at_startup()
message = str(exc.value)
assert "prod" in message
assert "legacy" in message
assert "read" in message
assert "native" in message
def test_tc4_all_seven_gating_sources_parse_with_case_and_whitespace(monkeypatch):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "native")
monkeypatch.setenv(
config.INTERACTION_NATIVE_SOURCES,
" Internal, SDK ,a2a,TRIGGER,widget,Shared_Link,Channel",
)
policy = ir.validate_interaction_rollout_at_startup()
assert policy.native_sources == frozenset(
{"internal", "sdk", "a2a", "trigger", "widget", "shared_link", "channel"}
)
def test_tc5_unknown_source_and_duplicate_source_raise_distinct_messages(monkeypatch):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "native")
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, "sdk,bogus")
with pytest.raises(ir.InteractionRolloutConfigError) as exc_unknown:
ir.validate_interaction_rollout_at_startup()
unknown_message = str(exc_unknown.value)
monkeypatch.setattr(ir, "_policy", None)
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, "sdk,sdk")
with pytest.raises(ir.InteractionRolloutConfigError) as exc_dup:
ir.validate_interaction_rollout_at_startup()
dup_message = str(exc_dup.value)
assert "bogus" in unknown_message
assert "sdk" in dup_message
assert unknown_message != dup_message
assert "more than once" in dup_message
assert "more than once" not in unknown_message
def test_tc6_native_mode_with_empty_sources_raises(monkeypatch):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "native")
with pytest.raises(ir.InteractionRolloutConfigError):
ir.validate_interaction_rollout_at_startup()
def test_tc7_legacy_with_nonempty_sources_does_not_raise_but_logs_info(
monkeypatch, caplog
):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "legacy")
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, "sdk")
with caplog.at_level(
logging.INFO, logger="xagent.web.services.interaction_rollout"
):
policy = ir.validate_interaction_rollout_at_startup()
assert policy.mode == "legacy"
assert policy.native_sources == frozenset({"sdk"})
assert any(
"no effect until mode is switched to native" in r.message
for r in caplog.records
)
def test_tc8_blank_entries_are_skipped_not_raised(monkeypatch):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "native")
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, "sdk,,a2a")
policy = ir.validate_interaction_rollout_at_startup()
assert policy.native_sources == frozenset({"sdk", "a2a"})
def test_tc9_policy_is_frozen():
policy = ir.validate_interaction_rollout_at_startup()
with pytest.raises(dataclasses.FrozenInstanceError):
policy.mode = "native" # type: ignore[misc]
def test_tc12_idempotent_returns_same_object_identity(monkeypatch):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "read")
first = ir.validate_interaction_rollout_at_startup()
second = ir.validate_interaction_rollout_at_startup()
assert first is second
def test_tc13_uninitialized_singleton_raises_runtime_error_not_lazy_parse():
with pytest.raises(RuntimeError):
ir.get_interaction_rollout_policy()
def test_tc14_trigger_in_allowlist_warns_but_does_not_raise(monkeypatch, caplog):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, "native")
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, "trigger")
with caplog.at_level(
logging.WARNING, logger="xagent.web.services.interaction_rollout"
):
policy = ir.validate_interaction_rollout_at_startup()
assert policy.native_sources == frozenset({"trigger"})
assert any("no interactive responder" in r.message for r in caplog.records)
_ROLLOUT_LOGGER = "xagent.web.services.interaction_rollout"
_NATIVE_WITHOUT_SHARED_EXECUTION_WARNING = (
f"{config.INTERACTION_PROTOCOL_MODE}=native but this process is not running "
f"shared task execution (see {config.SHARED_TASK_EXECUTION_ENABLED}), so "
"native publication will never happen in this process."
)
@pytest.mark.parametrize(
("mode", "topology_env", "expected_shared", "expected_warnings"),
[
pytest.param(
"native",
{config.SHARED_TASK_EXECUTION_ENABLED: "false"},
False,
[_NATIVE_WITHOUT_SHARED_EXECUTION_WARNING],
id="native_not_shared",
),
pytest.param(
"native",
{config.SHARED_TASK_EXECUTION_ENABLED: "true"},
True,
[],
id="native_shared",
),
pytest.param(
"legacy",
{config.SHARED_TASK_EXECUTION_ENABLED: "false"},
False,
[],
id="legacy_not_shared",
),
# Explicit flag unset: the topology is derived from the process
# role and worker count, the way split web/worker deployments run.
pytest.param(
"native",
{config.TASK_EXECUTION_ROLE: "web"},
True,
[],
id="native_derived_shared_from_web_role",
),
pytest.param(
"native",
{},
False,
[_NATIVE_WITHOUT_SHARED_EXECUTION_WARNING],
id="native_derived_not_shared_when_unconfigured",
),
],
)
def test_tc15_topology_is_frozen_at_startup_and_only_native_without_shared_execution_warns(
monkeypatch, caplog, mode, topology_env, expected_shared, expected_warnings
):
monkeypatch.setenv(config.INTERACTION_PROTOCOL_MODE, mode)
if mode == "native":
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, "sdk")
for name in (
config.SHARED_TASK_EXECUTION_ENABLED,
config.TASK_EXECUTION_ROLE,
config.WORKER_COUNT,
):
monkeypatch.delenv(name, raising=False)
for name, value in topology_env.items():
monkeypatch.setenv(name, value)
with caplog.at_level(logging.INFO, logger=_ROLLOUT_LOGGER):
policy = ir.validate_interaction_rollout_at_startup()
assert policy.mode == mode
assert policy.shared_task_execution is expected_shared
assert [
record.getMessage()
for record in caplog.records
if record.name == _ROLLOUT_LOGGER and record.levelno == logging.WARNING
] == expected_warnings
policy_lines = [
record.getMessage()
for record in caplog.records
if record.name == _ROLLOUT_LOGGER
and record.levelno == logging.INFO
and record.getMessage().startswith("Interaction rollout policy configured:")
]
assert len(policy_lines) == 1
assert policy_lines[0].rpartition(" shared_task_execution=")[2] == str(
expected_shared
)
# Flip the topology after startup: the live resolver follows the
# environment, the policy the gate reads does not.
monkeypatch.setenv(
config.SHARED_TASK_EXECUTION_ENABLED, "false" if expected_shared else "true"
)
assert config.get_shared_task_execution_enabled() is not expected_shared
assert ir.get_interaction_rollout_policy().shared_task_execution is expected_shared
def test_tc10a_origin_vocabulary_equals_check_constraint_in_list():
check = next(
c
for c in TaskInteractionRequest.__table__.constraints
if getattr(c, "name", None) == "ck_task_interaction_requests_origin"
)
values = frozenset(re.findall(r"'([^']+)'", check.sqltext.text))
assert INTERACTION_ORIGIN_VOCABULARY == values
def test_tc10b_task_source_literals_is_a_strict_subset_of_vocabulary():
assert TASK_SOURCE_LITERALS <= INTERACTION_ORIGIN_VOCABULARY
assert TASK_SOURCE_LITERALS != INTERACTION_ORIGIN_VOCABULARY
assert INTERACTION_ORIGIN_VOCABULARY - TASK_SOURCE_LITERALS == {"internal"}
def test_tc10c_gating_sources_is_origin_vocabulary_plus_channel_only():
assert ir.INTERACTION_GATING_SOURCES >= INTERACTION_ORIGIN_VOCABULARY
assert ir.INTERACTION_GATING_SOURCES - INTERACTION_ORIGIN_VOCABULARY == {"channel"}
# ---------------------------------------------------------------------------
# T-S: Task.source normalization -- LIVE spec, no strip/lower
# ---------------------------------------------------------------------------
@pytest.mark.parametrize("value", [None, ""])
def test_ts1_falsy_normalizes_to_internal(value):
assert normalize_interaction_origin(value) == "internal"
def test_ts2_whitespace_only_is_unknown_not_internal():
assert normalize_interaction_origin(" ") is None
@pytest.mark.parametrize(
"value", ["internal", "sdk", "a2a", "trigger", "widget", "shared_link"]
)
def test_ts3_exact_vocabulary_matches_pass_through(value):
assert normalize_interaction_origin(value) == value
@pytest.mark.parametrize("value", [" sdk", "SDK", "sdk "])
def test_ts4_near_matches_are_unknown_not_coerced(value):
assert normalize_interaction_origin(value) is None
def test_ts5_unrecognized_free_text_is_unknown_not_internal():
assert normalize_interaction_origin("something-else") is None
def test_ts6_env_side_source_list_still_strips_and_lowers(monkeypatch):
monkeypatch.setenv(config.INTERACTION_NATIVE_SOURCES, " SDK , a2a")
assert config.get_interaction_native_sources() == ["sdk", "a2a"]