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
# 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