Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
23.9 KB
Raw Blame
# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.

"""Unit tests for the A2UI integration bridge.

The bridge keeps A2UI-specific request/config/fallback decisions out of the
core AgentServer and Gateway modules.
"""

from __future__ import annotations

import builtins

import pytest

from jiuwenswarm.server.runtime.a2ui import integration
from jiuwenswarm.server.runtime.a2ui.integration import (
    apply_non_web_text_fallback_to_payload,
    build_user_prompt_if_a2ui_event,
    get_a2ui_config_payload,
    is_a2ui_channel,
    validate_a2ui_config_update,
)


def test_a2ui_channel_policy_covers_web_and_officeclaw():
    """A2UI native channels are the controlled Web channel + officeclaw (relay-claw);
    all other channels stay off."""
    assert is_a2ui_channel("web") is True
    assert is_a2ui_channel("WEB") is True
    assert is_a2ui_channel("officeclaw") is True
    assert is_a2ui_channel("OfficeClaw") is True
    assert is_a2ui_channel("feishu") is False
    assert is_a2ui_channel("wechat") is False
    assert is_a2ui_channel(None) is False


def test_build_user_prompt_if_a2ui_event_disabled_returns_none(monkeypatch):
    """Disabled A2UI should leave client-event payloads to normal handling."""
    monkeypatch.setenv("JIUWENSWARM_A2UI_ENABLED", "false")
    event = {"type": "a2ui.client_event", "userAction": {"context": {"value": "ok"}}}

    assert build_user_prompt_if_a2ui_event(event, channel="web", language="zh") is None


def test_build_user_prompt_if_a2ui_event_enabled_mentions_context(monkeypatch):
    """Enabled A2UI should translate client events into model-readable prompts."""
    monkeypatch.setenv("JIUWENSWARM_A2UI_ENABLED", "true")
    monkeypatch.setattr(
        integration,
        "_build_a2ui_client_event_prompt",
        lambda content, channel, language: (
            f"{content['type']} on {channel}/{language}: context={content['userAction']['context']}"
        ),
    )
    event = {"type": "a2ui.client_event", "userAction": {"context": {"value": "ok"}}}

    prompt = build_user_prompt_if_a2ui_event(event, channel="web", language="zh")

    assert prompt is not None
    assert "a2ui.client_event" in prompt
    assert "context" in prompt


def test_build_user_prompt_if_a2ui_event_bypasses_non_web_channel(monkeypatch):
    """Non-Web channels should not perceive structured A2UI client events."""
    monkeypatch.setenv("JIUWENSWARM_A2UI_ENABLED", "true")
    event = {"type": "a2ui.client_event", "userAction": {"context": {"value": "ok"}}}

    assert build_user_prompt_if_a2ui_event(event, channel="feishu", language="zh") is None


def test_apply_non_web_text_fallback_skips_web_payload(monkeypatch):
    """Web messages must keep raw A2UI blocks for the frontend renderer."""
    monkeypatch.setenv("JIUWENSWARM_A2UI_ENABLED", "true")
    payload = {
        "event_type": "chat.final",
        "content": "hello <a2ui-json>[]</a2ui-json>",
    }

    assert apply_non_web_text_fallback_to_payload(payload, channel_id="web") is payload


def test_apply_non_web_text_fallback_bypasses_non_web_payload(monkeypatch):
    """Non-Web payloads should bypass A2UI fallback even when A2UI is enabled."""
    monkeypatch.setenv("JIUWENSWARM_A2UI_ENABLED", "true")
    payload = {
        "event_type": "chat.final",
        "content": "hello <a2ui-json>[]</a2ui-json>",
    }

    assert apply_non_web_text_fallback_to_payload(payload, channel_id="telegram") is payload
    assert payload["content"] == "hello <a2ui-json>[]</a2ui-json>"


def test_message_handler_fallback_skips_a2ui_import_without_marker(monkeypatch):
    """Gateway hot path should not import A2UI when payload has no A2UI marker."""
    from jiuwenswarm.gateway.message_handler.message_handler import (
        apply_a2ui_text_fallback_to_gateway_payload,
    )

    real_import = builtins.__import__

    def guard_import(name, *args, **kwargs):
        if name == "jiuwenswarm.server.runtime.a2ui.integration":
            raise AssertionError("A2UI integration should not be imported")
        return real_import(name, *args, **kwargs)

    monkeypatch.setattr(builtins, "__import__", guard_import)
    payload = {"event_type": "chat.final", "content": "plain text"}

    assert apply_a2ui_text_fallback_to_gateway_payload(payload, channel_id="telegram") is payload


def test_get_a2ui_config_payload_defaults():
    """Config payloads should expose only user-facing A2UI Web keys."""
    payload = get_a2ui_config_payload({"a2ui": {}})

    assert payload == {"a2ui_enabled": "false"}


def test_validate_a2ui_config_update_rejects_internal_keys():
    """Internal A2UI settings should not be mutable from the Web config page."""
    ok, update, error = validate_a2ui_config_update("a2ui_protocol_version", "0.9")

    assert ok is False
    assert update == {}
    assert "Unknown A2UI config key" in error


def test_validate_a2ui_config_update_maps_boolean_key():
    """Web config keys should map to the YAML keys owned by the A2UI config."""
    ok, update, error = validate_a2ui_config_update("a2ui_enabled", "false")

    assert ok is True
    assert update == {"enabled": False}
    assert error == ""


def test_normal_text_prompt_builder_keeps_string_flow(monkeypatch):
    """Non-A2UI string input should keep the normal prompt builder path."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import build_user_prompt

    monkeypatch.setenv("JIUWENSWARM_A2UI_ENABLED", "true")

    prompt = build_user_prompt("你好", files={}, channel="web", language="zh")

    assert '"content": "你好"' in prompt
    assert '"type": "user input"' in prompt


def test_a2ui_stream_probe_detects_split_protocol_marker():
    """Stream suppression should survive protocol markers split across chunks."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _extend_a2ui_stream_probe,
        _stream_probe_has_a2ui_marker,
    )

    probe = ""
    probe = _extend_a2ui_stream_probe(probe, "好的,开始整理。\n\nbeginRend")

    assert _stream_probe_has_a2ui_marker(probe) is True

    probe = _extend_a2ui_stream_probe(probe, "ering")

    assert _stream_probe_has_a2ui_marker(probe) is True


def test_a2ui_stream_probe_ignores_regular_begin_text():
    """Plain text containing begin-like words should keep normal streaming."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _extend_a2ui_stream_probe,
        _stream_probe_has_a2ui_marker,
    )

    probe = _extend_a2ui_stream_probe("", "I will begin by summarizing the mailbox.")

    assert _stream_probe_has_a2ui_marker(probe) is False


def test_a2ui_stream_probe_ignores_begin_sentence_at_line_start():
    """A normal sentence starting with begin should not look like A2UI."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _extend_a2ui_stream_probe,
        _stream_probe_has_a2ui_marker,
    )

    probe = _extend_a2ui_stream_probe("", "begin by summarizing the mailbox.")

    assert _stream_probe_has_a2ui_marker(probe) is False


def test_split_a2ui_stream_content_keeps_prefix_streamable():
    """Only A2UI protocol text should be suppressed from a mixed chunk."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import _split_a2ui_stream_content

    split = _split_a2ui_stream_content(
        "",
        "浏览器代理已完成搜索和整理,现在为你展示结果。\n\nbeginRendering\n邮件整理完成",
    )

    assert split == (
        "浏览器代理已完成搜索和整理,现在为你展示结果。\n\n",
        "beginRendering\n邮件整理完成",
    )


def test_split_a2ui_stream_content_handles_partial_marker():
    """A partial marker long enough to be distinctive should suppress only the marker line."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import _split_a2ui_stream_content

    split = _split_a2ui_stream_content("", "现在为你展示结果。\n\nbeginRend")

    assert split == ("现在为你展示结果。\n\n", "beginRend")


def test_split_a2ui_stream_content_ignores_short_tag_prefix():
    """A short '<a' fragment must not trigger A2UI suppression (false-positive guard)."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import _split_a2ui_stream_content

    split = _split_a2ui_stream_content("", "现在为你展示结果。\n\n<a")

    assert split is None


def test_split_a2ui_stream_content_suppresses_long_tag_prefix():
    """A distinctive '<a2ui-js' prefix should trigger suppression."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import _split_a2ui_stream_content

    split = _split_a2ui_stream_content("", "现在为你展示结果。\n\n<a2ui-js")

    assert split == ("现在为你展示结果。\n\n", "<a2ui-js")


def test_a2ui_pending_render_delta_stays_open():
    """The Web renderer shows its pending state only for an open A2UI block."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import _A2UI_PENDING_RENDER_DELTA

    assert _A2UI_PENDING_RENDER_DELTA.startswith("<a2ui-json>")
    assert "</a2ui-json>" not in _A2UI_PENDING_RENDER_DELTA


def test_a2ui_repaired_final_chunk_keeps_session_binding():
    """The repaired final must replace the pending A2UI bubble in its session.

    §9.1 契约:重发帧带 a2ui_resend=True。suppress 期间 wire 上已流出
    半截 `<a2ui` + probe 占位(relay 侧 delta 累积);降级终稿可能不含
    <a2ui-json> 标签,relay 的 replace_final 原本按标签门控不覆写,残片
    会留在正文。带 a2ui_resend 标记即声明"这是权威终稿,无条件整段覆写"。
    """
    from jiuwenswarm.server.runtime.agent_adapter.interface import _make_a2ui_final_chunk

    chunk = _make_a2ui_final_chunk(
        request_id="req-a2ui",
        channel_id="web",
        session_id="sess-a2ui",
        content="<a2ui-json>[]</a2ui-json>",
    )

    assert chunk.payload == {
        "event_type": "chat.final",
        "session_id": "sess-a2ui",
        "content": "<a2ui-json>[]</a2ui-json>",
        "a2ui_resend": True,
    }


def test_a2ui_processing_false_waits_for_repaired_final():
    """A2UI finalization must finish before the frontend closes its stream."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _should_defer_a2ui_processing_status,
    )

    payload = {
        "event_type": "chat.processing_status",
        "is_processing": False,
    }

    assert _should_defer_a2ui_processing_status(
        suppress_a2ui_stream=True,
        event_type="chat.processing_status",
        payload=payload,
    ) is True
    assert _should_defer_a2ui_processing_status(
        suppress_a2ui_stream=False,
        event_type="chat.processing_status",
        payload=payload,
    ) is False


def test_nested_stream_completion_waits_for_facade_post_processing():
    """The adapter terminal must not close the wire before A2UI finalization."""
    from jiuwenswarm.common.schema.agent import AgentResponseChunk
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _normalize_nested_stream_chunk,
    )

    terminal = AgentResponseChunk(
        request_id="req-a2ui",
        channel_id="web",
        payload=None,
        is_complete=True,
    )

    assert _normalize_nested_stream_chunk(terminal) is None


def test_nested_terminal_event_remains_visible_without_closing_stream():
    """A meaningful terminal event is retained while the facade owns completion."""
    from jiuwenswarm.common.schema.agent import AgentResponseChunk
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _normalize_nested_stream_chunk,
    )

    terminal_error = AgentResponseChunk(
        request_id="req-error",
        channel_id="web",
        payload={"event_type": "chat.error", "error": "failed"},
        is_complete=True,
    )

    normalized = _normalize_nested_stream_chunk(terminal_error)

    assert normalized is not None
    assert normalized.payload == terminal_error.payload
    assert normalized.is_complete is False


def test_agent_prompt_builder_accepts_a2ui_client_event_dict(monkeypatch):
    """Structured Web A2UI events should bypass normal text prompt wrapping."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import build_user_prompt

    monkeypatch.setenv("JIUWENSWARM_A2UI_ENABLED", "true")

    prompt = build_user_prompt(
        {
            "type": "a2ui.client_event",
            "protocolVersion": "0.8",
            "event": {
                "userAction": {
                    "name": "submit_form",
                    "surfaceId": "surface-1",
                    "sourceComponentId": "submit",
                    "context": {"name": "张三"},
                },
            },
        },
        files={},
        channel="web",
        language="zh",
    )

    assert "你收到了一次 A2UI 组件交互" in prompt
    assert "submit_form" in prompt
    assert "张三" in prompt


@pytest.mark.asyncio
async def test_finalize_assistant_response_if_a2ui_noops_when_config_lookup_fails(monkeypatch):
    """A2UI finalization must not break the core agent response path."""
    def fail_config_lookup():
        raise RuntimeError("config unavailable")

    async def repair_call(prompt: str):
        raise AssertionError("repair should not run when A2UI config is unavailable")

    monkeypatch.setattr(integration, "_get_runtime_a2ui_config", fail_config_lookup)

    content = "<a2ui-json>[]</a2ui-json>"
    result = await integration.finalize_assistant_response_if_a2ui(
        content,
        user_query="generate a form",
        request_id="req-config-error",
        repair_call=repair_call,
    )

    assert result == content


@pytest.mark.asyncio
async def test_finalize_assistant_response_if_a2ui_bypasses_non_web_channel(monkeypatch):
    """Non-Web responses should not run A2UI config lookup, validation, or repair."""
    def fail_config_lookup():
        raise AssertionError("non-Web channel should bypass A2UI config lookup")

    async def repair_call(prompt: str):
        raise AssertionError("repair should not run for non-Web channels")

    monkeypatch.setattr(integration, "_get_runtime_a2ui_config", fail_config_lookup)

    content = "<a2ui-json>[]</a2ui-json>"
    result = await integration.finalize_assistant_response_if_a2ui(
        content,
        channel="feishu",
        user_query="generate a form",
        request_id="req-non-web",
        repair_call=repair_call,
    )

    assert result == content


@pytest.mark.asyncio
async def test_finalize_officeclaw_runs_server_side_repair_and_resend(monkeypatch):
    """officeclaw (relay-claw) now runs server-side A2UI repair/retry/resend.

    officeclaw 启用 probe + suppress + repair(与 web 对齐)。suppress 扣住原 chat.final
    + 改写 is_complete,relay-claw 不 break;relay-claw 前端已部署 chat.final a2ui
    replace_final 覆写(patchMessage({content}=finalized)),覆写掉 delta 累积的
    <a2ui 前半 + probe 污染。repair 修复破损 JSON,发送 finalized(前端首次收到)。
    """
    import types

    config_calls: list[int] = []

    def fake_config():
        config_calls.append(1)
        return types.SimpleNamespace(enabled=True)

    monkeypatch.setattr(integration, "_get_runtime_a2ui_config", fake_config)

    finalize_calls: list[str] = []

    async def fake_finalize(content, **kwargs):
        finalize_calls.append(content)
        return content

    monkeypatch.setattr(
        "jiuwenswarm.server.runtime.a2ui.runtime.response_finalization.finalize_a2ui_assistant_content",
        fake_finalize,
    )

    repair_calls: list[str] = []

    async def repair_call(prompt: str):
        repair_calls.append(prompt)
        return prompt

    retry_calls: list[str] = []

    def retry_without_a2ui_call(query: str):
        retry_calls.append(query)
        return "retry content"

    broken_a2ui = "<a2ui-json>{broken json</a2ui-json>"
    result = await integration.finalize_assistant_response_if_a2ui(
        broken_a2ui,
        channel="officeclaw",
        user_query="generate a form",
        request_id="req-officeclaw",
        repair_call=repair_call,
        retry_without_a2ui_call=retry_without_a2ui_call,
    )

    # officeclaw 现在走 repair(不再跳过)
    # fake_finalize 原样返回入参,result 应等于 broken_a2ui
    assert result == broken_a2ui
    assert config_calls == [1]
    assert len(finalize_calls) == 1
    # repair_call / retry_without_a2ui_call 传给 finalize 守卫,未被直接调用(fake_finalize 短路)
    # 但列表不应有遗漏的意外调用
    assert repair_calls == []
    assert retry_calls == []


@pytest.mark.parametrize("channel,expected", [
    ("web", True),
    ("officeclaw", True),
    ("feishu", False),
    (None, False),
])
def test_a2ui_probe_channel_whitelist(channel, expected):
    """白名单回归保护:officeclaw 启用 probe 后不可被误改回去。"""
    assert integration.is_a2ui_probe_channel(channel) is expected


@pytest.mark.parametrize("channel,expected", [
    ("web", True),
    ("officeclaw", True),
    ("feishu", False),
    (None, False),
])
def test_finalize_repair_whitelist(channel, expected):
    """白名单回归保护:officeclaw 启用 repair 后不可被误改回去。"""
    assert integration.should_finalize_repair(channel) is expected


@pytest.mark.asyncio
async def test_finalize_web_still_runs_server_side_repair(monkeypatch):
    """web must keep running server-side A2UI repair/retry/resend (regression guard)."""
    import types

    def fake_config():
        return types.SimpleNamespace(enabled=True)

    monkeypatch.setattr(integration, "_get_runtime_a2ui_config", fake_config)

    finalize_calls: list[str] = []

    async def fake_finalize(content, **kwargs):
        finalize_calls.append(content)
        return content

    monkeypatch.setattr(
        "jiuwenswarm.server.runtime.a2ui.runtime.response_finalization.finalize_a2ui_assistant_content",
        fake_finalize,
    )

    content = "<a2ui-json>[]</a2ui-json>"
    result = await integration.finalize_assistant_response_if_a2ui(
        content,
        channel="web",
        user_query="generate a form",
        request_id="req-web",
        repair_call=None,
    )

    assert result == content
    assert finalize_calls == [content]


def test_partial_marker_ignores_short_data_token():
    """'data' alone must not trigger A2UI suppression (ECharts false-positive)."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _looks_like_partial_a2ui_marker,
    )

    assert _looks_like_partial_a2ui_marker("some content\ndata") is False


def test_partial_marker_ignores_data_with_array():
    """'data: [1,2,3]' must not trigger A2UI suppression."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _looks_like_partial_a2ui_marker,
    )

    assert _looks_like_partial_a2ui_marker("chart.setOption({\ndata: [1, 2, 3]\n})") is False


def test_partial_marker_ignores_aside_tag():
    """'<aside>' must not trigger A2UI suppression (HTML false-positive)."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _looks_like_partial_a2ui_marker,
    )

    assert _looks_like_partial_a2ui_marker("content\n<aside>") is False


def test_partial_marker_ignores_beginning_word():
    """'beginning' must not trigger A2UI suppression."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _looks_like_partial_a2ui_marker,
    )

    assert _looks_like_partial_a2ui_marker("in the beginning") is False


def test_partial_marker_ignores_delete_token():
    """'delete' alone must not trigger A2UI suppression."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _looks_like_partial_a2ui_marker,
    )

    assert _looks_like_partial_a2ui_marker("code\n\ndelete") is False


def test_partial_marker_ignores_surface_token():
    """'surface' alone must not trigger A2UI suppression."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _looks_like_partial_a2ui_marker,
    )

    assert _looks_like_partial_a2ui_marker("render\nsurface") is False


def test_partial_marker_triggers_on_long_dataModel_prefix():
    """'dataModel' is long enough to be distinctive and should trigger."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _looks_like_partial_a2ui_marker,
    )

    assert _looks_like_partial_a2ui_marker("content\ndataModel") is True


def test_suppress_engage_ignores_foreign_frames():
    """Nested-stream mirror frames must never engage the parent's suppression.

    Regression: a member/skill-node delta whose mirrored text carries a2ui
    markers used to trip the parent state machine — withholding the parent's
    stream, emitting a spurious render probe and mixing child text into the
    finalized answer.
    """
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _a2ui_suppress_should_engage,
    )

    # Main-chain marker frame engages first-time suppression; foreign does not.
    assert _a2ui_suppress_should_engage(False, ("prefix", "rest"), False) is True
    assert _a2ui_suppress_should_engage(False, ("prefix", "rest"), True) is False
    # No marker: nobody engages.
    assert _a2ui_suppress_should_engage(False, None, False) is False
    # Once the parent is suppressing, every frame stays withheld (flag belongs
    # to the parent turn, not the frame that set it).
    assert _a2ui_suppress_should_engage(True, None, True) is True


def test_foreign_source_predicate_semantics():
    """chat.delta guards must use the same foreign predicate as reasoning/tool_call."""
    from jiuwenswarm.server.runtime.agent_adapter.interface import (
        _is_foreign_stream_source,
    )

    assert _is_foreign_stream_source({"stream_source_id": "node-7"}) is True
    assert _is_foreign_stream_source({"stream_source_id": "main"}) is False
    assert _is_foreign_stream_source({}) is False
    assert _is_foreign_stream_source(None) is False


# ── CR 三连击回归(renquanjia 2026-10-29 #1/#2/#3):foreign 判定必须前置到
# probe/split 之前,子流 marker 不得进入父轮 probe 窗口;engage/durable/normal
# 各路径的父轮 bookkeeping(final_answer_content/durable 缓冲)不得被子流帧改写。

def test_probe_frame_gate_skips_foreign_frames():
    """CR#2 回归:foreign 帧不得扩展父轮 probe、不得产出 split。

    旧序:split+extend 先算、foreign 后判——子流 chat.delta 含 <a2ui-json> 时
    marker 滞留父轮 probe(512B 窗口),下一条主链帧 combined=probe+content
    命中 marker_start<=content_start → split=("",content) → 主链被误 suppress、
    扣发文本、发 spurious 占位帧。
    """
    from jiuwenswarm.server.runtime.agent_adapter.interface import _a2ui_probe_for_frame

    split, probe = _a2ui_probe_for_frame(
        probe="ok ", content="前文", event_type="chat.delta", enabled=True, foreign=True,
    )
    assert split is None
    assert probe == "ok "  # 子流帧完全不接触父轮 probe

    # foreign 的 marker 帧同样不进 probe
    split, probe = _a2ui_probe_for_frame(
        probe="", content="hello <a2ui-json>", event_type="chat.delta", enabled=True, foreign=True,
    )
    assert split is None
    assert probe == ""

    # 主链帧行为不变:marker 产出 split 且 probe 累积
    split, probe = _a2ui_probe_for_frame(
        probe="", content="hello <a2ui-json>", event_type="chat.delta", enabled=True, foreign=False,
    )
    assert split is not None
    assert "<a2ui-json>" in probe


def test_suppress_engage_gate_semantics_unchanged():
    """gate 分工锚定:suppress 激活后 foreign 帧仍 withhold(True),
    未激活时仅非 foreign 且有 split 才 engage。父轮 bookkeeping 守卫在调用点,
    若未来把 withhold 与 bookkeeping 合并回 gate,本用例会以语义变化提醒。"""
    from jiuwenswarm.server.runtime.agent_adapter.interface import _a2ui_suppress_should_engage

    assert _a2ui_suppress_should_engage(True, None, True) is True   # suppress 后 foreign 维持扣发
    assert _a2ui_suppress_should_engage(False, ("", "x"), True) is False  # 未激活时 foreign 不 engage
    assert _a2ui_suppress_should_engage(False, ("", "x"), False) is True