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.
from __future__ import annotations
import asyncio
import json
import sys
from pathlib import Path
import pytest
from jiuwenswarm.common.e2a.wire_codec import (
encode_agent_chunk_for_wire,
encode_agent_response_for_wire,
)
from jiuwenswarm.common.schema.agent import AgentResponse, AgentResponseChunk
from jiuwenswarm.common.schema.message import ReqMethod
from jiuwenswarm.server.agent_ws_server import AgentWebSocketServer
from jiuwenswarm.server.dispatch import HANDLERS, dispatch_to_handler, supported_methods
from jiuwenswarm.server.handlers import session as session_handlers
from jiuwenswarm.server.transports.sink import (
STREAM_DONE,
ResponseSink,
SSESink,
UnaryHTTPSink,
WSSink,
)
class _RecordingServer:
def __init__(self) -> None:
self.calls: list[tuple[str, tuple, dict]] = []
def __getattr__(self, name: str):
async def _call(*args, **kwargs):
# 前三个位置参数固定为 (ws, request, send_lock),其后才是 spec.args
self.calls.append((name, args[3:], kwargs))
return _call
class _Req:
def __init__(self, method: ReqMethod, *, is_stream: bool = False) -> None:
self.req_method = method
self.is_stream = is_stream
_DISPATCH_TABLE_METHODS = frozenset({
"AGENTS_CREATE", "AGENTS_DELETE", "AGENTS_DISABLE", "AGENTS_ENABLE", "AGENTS_GET",
"AGENTS_LIST", "AGENTS_TOOLS_LIST", "AGENTS_UPDATE", "AGENT_PREWARM_SYNC",
"AGENT_RELOAD_CONFIG", "BROWSER_RUNTIME_RESTART", "CHAT_CANCEL",
"CHAT_STEER", "CHAT_STEER_STATUS", "COMMAND_ADD_DIR",
"COMMAND_BTW", "COMMAND_CHROME", "COMMAND_COMPACT", "COMMAND_COMPACT_PARTIAL",
"COMMAND_CONTEXT", "COMMAND_DIFF", "COMMAND_MCP", "MCP_SERVER_ADD",
"MCP_SERVER_GET", "MCP_SERVER_LIST", "MCP_SERVER_REMOVE", "MCP_SERVER_UPDATE",
"COMMAND_MODEL", "COMMAND_RECAP",
"COMMAND_RESUME", "COMMAND_SANDBOX", "COMMAND_SESSION", "COMMAND_SIMPLIFY",
"COMMAND_STATUS", "COMMAND_WORKFLOWS", "CONFIG_CACHE_CLEAR", "EXTENSIONS_DELETE",
"EXTENSIONS_IMPORT", "EXTENSIONS_LIST", "EXTENSIONS_TOGGLE",
"FILE_TRANSFER_CHUNK", "FILE_TRANSFER_COMPLETE", "FILE_TRANSFER_START",
"HARNESS_PACKAGES_ACTIVATE", "HARNESS_PACKAGES_DEACTIVATE",
"HARNESS_PACKAGES_DELETE", "HARNESS_PACKAGES_GET", "HARNESS_PACKAGES_SCAN",
"HISTORY_GET", "HOOKS_LIST",
"IM_HOSTING_DISCOVER", "IM_HOSTING_POLICY_GET", "IM_HOSTING_POLICY_PATCH",
"IM_HOSTING_HISTORY", "IM_HOSTING_POLL_NOW", "IM_HOSTING_STATUS",
"IM_HOSTING_LOGIN_START", "IM_HOSTING_LOGIN_STATUS",
"IM_HOSTING_TARGETS_ADD", "IM_HOSTING_TARGETS_DELETE",
"IM_HOSTING_TARGETS_LIST", "IM_HOSTING_TARGETS_PATCH",
"ISSUE_DELETE", "ISSUE_MATRIX", "ISSUE_STATE_LIST",
"ISSUE_WATCH_ONCE", "LONG_HORIZON", "PROACTIVE_TICK", "SCHEDULE_CANCEL", "SCHEDULE_CHECK_CONFIG",
"SCHEDULE_CREATE", "SCHEDULE_DELETE", "SCHEDULE_LIST", "SCHEDULE_LOGS",
"SCHEDULE_RUN", "SCHEDULE_STATUS", "SCHEDULE_UPDATE_CONFIG", "SESSION_DELETE",
"SESSION_LIST", "SESSION_RENAME", "SESSION_REWIND", "SESSION_REWIND_AND_RESTORE",
"SESSION_REWIND_COMPACT", "SESSION_REWIND_CONTEXT", "SESSION_SWITCH",
"SYNC_AGENTS_CONFIGS", "TEAM_BINDINGS_LIST", "TEAM_BINDING_CREATE",
"TEAM_BINDING_GENERATE", "TEAM_DELETE", "TEAM_HISTORY_GET", "TEAM_MEMBERS_GET",
"TEAM_MQ_PUBLISH", "TEAM_RUNTIME_DISSOLVE", "TEAM_SESSION_BIND", "TEAM_SESSION_RESET", "TEAM_SNAPSHOT",
"TEAM_TASKS_DEPENDENCIES", "TEAM_TEMPLATES_LIST",
})
_BOOTSTRAP_METHODS = frozenset({
"INITIALIZE", "SESSION_CREATE", "SESSION_FORK", "ACP_TOOL_RESPONSE",
})
def _permissions_methods() -> set[str]:
from jiuwenswarm.agents.harness.common.rails.permissions.permissions_config_rpc import (
get_permissions_config_req_methods,
)
return {m.name for m in get_permissions_config_req_methods()}
def test_table_covers_expected_method_set() -> None:
expected = _DISPATCH_TABLE_METHODS | _permissions_methods() | _BOOTSTRAP_METHODS
current = {m.name for m in supported_methods()}
assert current == expected, (
f"仅在预期集合: {sorted(expected - current)}; 仅在表内: {sorted(current - expected)}"
)
@pytest.mark.parametrize("method", sorted(HANDLERS, key=lambda m: m.value), ids=lambda m: m.value)
def test_declared_handler_exists(method: ReqMethod) -> None:
spec = HANDLERS[method]
assert callable(spec.resolve_fn(False)), f"{method} 的 fn 不可调用"
if spec.stream_fn:
assert callable(spec.stream_fn), f"{method} 的 stream_fn 不可调用"
@pytest.mark.parametrize(
"method",
sorted((m for m, s in HANDLERS.items() if s.fn is not None), key=lambda m: m.value),
ids=lambda m: m.value,
)
def test_fn_signature_is_transport_free(method: ReqMethod) -> None:
import inspect
spec = HANDLERS[method]
for fn in filter(None, (spec.resolve_fn(False), spec.stream_fn)):
params = list(inspect.signature(fn).parameters)
assert inspect.iscoroutinefunction(fn), f"{fn.__name__} 应为 async"
assert "self" not in params, f"{fn.__name__} 是自由函数,不应有 self"
assert "ws" not in params, f"{fn.__name__} 仍带 ws 参数"
assert "send_lock" not in params, f"{fn.__name__} 仍带 send_lock 参数"
assert params[:1] == ["ctx"], f"{fn.__name__} 签名应为 (ctx, ...):{params}"
def test_fn_handlers_do_not_remain_on_server() -> None:
leftovers = sorted(
f"_{spec.resolve_fn(False).__name__}"
for spec in HANDLERS.values()
if spec.fn is not None
and hasattr(AgentWebSocketServer, f"_{spec.resolve_fn(False).__name__}")
)
assert not leftovers, f"这些 handler 在 handlers/ 里,但 server 上仍有同名方法:{leftovers}"
def test_handler_spec_requires_callable_fn() -> None:
from jiuwenswarm.server.dispatch import HandlerSpec as Spec
with pytest.raises(ValueError):
Spec() # 未指定 fn
with pytest.raises(ValueError):
Spec(fn="_not_callable") # 字符串(旧的 method 形态)
with pytest.raises(ValueError):
Spec(fn=lambda ctx: None, stream_fn="x") # stream_fn 也要可调用
@pytest.mark.parametrize(
"method",
sorted(HANDLERS, key=lambda m: m.value),
ids=lambda m: m.value,
)
def test_ctx_dispatch_invokes_with_context(method: ReqMethod) -> None:
from jiuwenswarm.server.context import RequestContext
seen: list[RequestContext] = []
async def fake_handler(ctx, *args, **kwargs):
seen.append(ctx)
spec = HANDLERS[method]
patched = type(spec)(fn=fake_handler, args=spec.args, kwargs=spec.kwargs)
sink = UnaryHTTPSink()
ctx = RequestContext(
request=_Req(method), sink=sink, connection_id="c1", services=None # type: ignore[arg-type]
)
HANDLERS[method] = patched
try:
handled = asyncio.run(
dispatch_to_handler(None, None, _Req(method), None, context_factory=lambda: ctx)
)
finally:
HANDLERS[method] = spec
assert handled is True
assert seen and seen[0].sink is sink
#: 不参与表分发的 handler —— 分发骨架与默认路径。
#: 新增例外必须在此显式登记,避免「迁了方法却忘了改表」悄悄溜过。
NON_DISPATCH_HANDLERS = frozenset(
{
"_handle_message", # 分发入口本身:字节 -> AgentRequest,属传输层
# sandbox.* 配置 E2A 的二级分发分支:_handle_message 尾部按
# get_sandbox_config_req_methods() 命中后直接调用,不登记主表(无 session、
# 非聊天语义);set 后需触发 reload_agents_config,故留在 server 上。
"_handle_sandbox_config",
}
)
def test_no_orphan_handler_methods() -> None:
import inspect
on_server = {
name
for name, _ in inspect.getmembers(AgentWebSocketServer, inspect.isfunction)
if name.startswith("_handle_")
}
orphans = sorted(on_server - NON_DISPATCH_HANDLERS)
assert not orphans, (
f"以下 handler 既不在分发表、也未登记为非分发:{orphans}\n"
f"若确属默认路径/其内部分支,请加入 NON_DISPATCH_HANDLERS 并说明原因。"
)
# 反向:清单里的名字必须**还在** server 上。
# 少了这半条,清单会悄悄腐烂 —— 例如 6 个 _handle_sandbox_* 移走后,
# 它们在清单里又躺了一轮没人发现;残留的名字等于给未来的同名方法发了张免检票。
stale = sorted(NON_DISPATCH_HANDLERS - on_server)
assert not stale, (
f"NON_DISPATCH_HANDLERS 里这些名字已不在 server 上(多半是迁走了):{stale}"
f" —— 请从清单删除,否则它对同名新方法就是一张静默免检票。"
)
def test_default_path_methods_are_not_in_table() -> None:
for method in [ReqMethod.CHAT_SEND, ReqMethod.CHAT_RESUME]:
assert method not in HANDLERS, f"{method} 不应在表内(它走默认路径)"
server = _RecordingServer()
handled = asyncio.run(dispatch_to_handler(server, None, _Req(method), None))
assert handled is False, f"{method} 应未命中以便落到默认路径"
def test_second_dispatch_point_is_merged() -> None:
import inspect
from jiuwenswarm.server.agent_ws_server import AgentWebSocketServer
for method in [
ReqMethod.INITIALIZE,
ReqMethod.SESSION_CREATE,
ReqMethod.SESSION_FORK,
ReqMethod.ACP_TOOL_RESPONSE,
]:
assert method in HANDLERS, f"{method} 应在主表内,不得另起分发"
fn = HANDLERS[method].resolve_fn(False)
src = inspect.getsource(fn)
assert "bootstrap_preconditions" in src, (
f"{fn.__name__} 未声明前置条件 —— 并表后 telemetry 绑定与 "
f"ensure_persistent_checkpointer 不再由调用链提供,必须显式包住方法体"
)
# 内层分发必须已从默认路径移除,否则会出现「两处都在管」
from jiuwenswarm.server.handlers import _default as default_path
impl_src = inspect.getsource(default_path._handle_unary_impl)
assert "ReqMethod.INITIALIZE" not in impl_src, (
"_handle_unary_impl 里仍残留第二处分发,与主表重复"
)
def test_history_get_stream_variant() -> None:
spec = HANDLERS[ReqMethod.HISTORY_GET]
assert spec.resolve_fn(True) is session_handlers.handle_history_get_stream
assert spec.resolve_fn(False) is session_handlers.handle_history_get
assert spec.resolve_fn(True) is not spec.resolve_fn(False)
def test_dispatch_raises_when_table_and_impl_diverge() -> None:
class Empty:
def __getattr__(self, name): # 模拟"没有该方法"
raise AttributeError(name)
with pytest.raises(AttributeError):
asyncio.run(dispatch_to_handler(Empty(), None, _Req(ReqMethod.SESSION_LIST), None))
def _resp() -> AgentResponse:
return AgentResponse(request_id="r1", channel_id="web", ok=True, payload={"a": 1})
class _FakeWS:
def __init__(self) -> None:
self.sent: list[str] = []
async def send(self, text: str) -> None:
self.sent.append(text)
def test_all_sinks_satisfy_protocol() -> None:
sinks = [WSSink(_FakeWS(), asyncio.Lock()), UnaryHTTPSink(), SSESink()]
assert all(isinstance(s, ResponseSink) for s in sinks)
_VOLATILE_TOP = ("timestamp",)
_VOLATILE_PROVENANCE = ("converted_at",)
def _stable(wire: dict) -> dict:
out = {k: v for k, v in wire.items() if k not in _VOLATILE_TOP}
prov = out.get("provenance")
if isinstance(prov, dict):
out["provenance"] = {k: v for k, v in prov.items() if k not in _VOLATILE_PROVENANCE}
return out
def test_ws_sink_wire_matches_legacy_encoding() -> None:
ws = _FakeWS()
resp = _resp()
asyncio.run(WSSink(ws, asyncio.Lock()).send_unary(resp))
actual = json.loads(ws.sent[0])
expected = encode_agent_response_for_wire(resp, response_id="r1")
assert _stable(actual) == _stable(expected)
assert actual.get("timestamp"), "timestamp 不应缺失"
ws2 = _FakeWS()
chunk = AgentResponseChunk(request_id="r1", channel_id="web", payload={"d": 9})
asyncio.run(WSSink(ws2, asyncio.Lock()).send_chunk(chunk, sequence=5))
actual2 = json.loads(ws2.sent[0])
expected2 = encode_agent_chunk_for_wire(chunk, response_id="r1", sequence=5)
assert _stable(actual2) == _stable(expected2)
assert actual2.get("sequence") == 5
def test_unary_http_sink_keeps_object_without_serializing() -> None:
sink = UnaryHTTPSink()
resp = _resp()
asyncio.run(sink.send_unary(resp))
assert sink.response is resp # 同一对象,未经序列化往返
def test_sse_sink_order_and_sentinel() -> None:
sink = SSESink()
async def run():
for i in range(3):
await sink.send_chunk(
AgentResponseChunk(request_id="r1", channel_id="web", payload={"i": i}),
sequence=i,
)
await sink.finish()
out = []
while True:
item = await sink.queue.get()
if item is STREAM_DONE:
return out
out.append(item)
frames = asyncio.run(run())
assert len(frames) == 3
assert all(isinstance(f, dict) for f in frames)
def test_oversized_payload_returns_false() -> None:
from jiuwenswarm.common.ws_limits import AGENT_WS_SEND_BUDGET_BYTES
big = AgentResponse(
request_id="r1",
channel_id="web",
ok=True,
payload={"x": "A" * (AGENT_WS_SEND_BUDGET_BYTES + 1024)},
)
sent = asyncio.run(WSSink(_FakeWS(), asyncio.Lock()).send_unary(big))
assert sent is False
def test_send_error_shape() -> None:
sink = UnaryHTTPSink()
asyncio.run(sink.send_error("r9", "boom", code="NOT_FOUND"))
assert sink.response is not None
assert sink.response.ok is False
assert sink.response.payload["code"] == "NOT_FOUND"
def test_no_duplicate_method_names_in_server_modules() -> None:
import ast
from pathlib import Path
server_dir = Path("jiuwenswarm/server")
if not server_dir.exists(): # 打包安装场景下跳过
pytest.skip("源码目录不可用")
# 既有重名的豁免登记。**保持为空**是目标状态:发现新的重名应当去修,而不是往这里加。
KNOWN_PREEXISTING: set[str] = set() # 曾有的一处已清理,保持为空即可
offenders: list[str] = []
# Large modules (e.g. interface_deep) can trip CPython AST recursion limits.
previous_limit = sys.getrecursionlimit()
sys.setrecursionlimit(max(previous_limit, 10000))
try:
for path in sorted(server_dir.rglob("*.py")):
if ".bak-" in path.name:
continue
try:
tree = ast.parse(path.read_text(encoding="utf-8"))
except SystemError as exc:
pytest.skip(f"ast.parse recursion limit on {path.as_posix()}: {exc}")
for node in ast.walk(tree):
if not isinstance(node, ast.ClassDef):
continue
seen: dict[str, int] = {}
for item in node.body:
if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
# @property / @x.setter 等合法重名:装饰器里带同名属性
decorated = any(
isinstance(d, ast.Attribute)
and d.attr in {"setter", "getter", "deleter"}
for d in item.decorator_list
)
key = f"{path.as_posix()}::{node.name}.{item.name}"
if item.name in seen and not decorated and key not in KNOWN_PREEXISTING:
offenders.append(
f"{path.as_posix()}:{item.lineno} {node.name}.{item.name} "
f"(先定义于第 {seen[item.name]} 行,将被覆盖)"
)
seen[item.name] = item.lineno
finally:
sys.setrecursionlimit(previous_limit)
assert not offenders, "发现重名方法(后者会静默覆盖前者):\n " + "\n ".join(offenders)
def test_service_members_matches_actual_handler_usage() -> None:
import ast
import pathlib
from jiuwenswarm.server.context import SERVICE_MEMBERS
from jiuwenswarm.server import handlers as handlers_pkg
handlers_dir = pathlib.Path(handlers_pkg.__file__).parent
# 扫描范围 = 全部 ctx.services 的消费者:handlers/<域>.py 与汇合点 pipeline.py。
# pipeline 也经 ctx.services 访问服务端(如按 connection_id 读 ACP 能力),
# 漏掉它会让清单里合法的成员被误判成「多余」。
sources = [py for py in sorted(handlers_dir.glob("*.py")) if py.name != "__init__.py"]
sources.append(handlers_dir.parent / "pipeline.py")
def _is_ctx_services(node: ast.AST) -> bool:
if isinstance(node, ast.Name) and node.id == "services":
return True
return (
isinstance(node, ast.Attribute)
and isinstance(node.value, ast.Name)
and node.value.id == "ctx"
and node.attr == "services"
)
used: set[str] = set()
for py in sources:
tree = ast.parse(py.read_text(encoding="utf-8"))
for node in ast.walk(tree):
# 形态一:属性语法 ctx.services.xxx
if isinstance(node, ast.Attribute) and _is_ctx_services(node.value):
used.add(node.attr)
# 形态二:动态访问 getattr/setattr/hasattr(ctx.services, "xxx", ...)
#
# 必须一并扫:``getattr(ctx.services, "x", None)`` 会把门面抛的
# AttributeError 吞成默认值 —— 越界访问**不报错、只是拿到 None**,
# 正是白名单最该拦住的那种静默失效。只看属性语法会漏掉它们。
elif (
isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id in {"getattr", "setattr", "hasattr"}
and len(node.args) >= 2
and _is_ctx_services(node.args[0])
and isinstance(node.args[1], ast.Constant)
and isinstance(node.args[1].value, str)
):
used.add(node.args[1].value)
# SERVICE_MEMBERS 是「门面公有名 → server 实际属性名」的映射,比对用 key。
missing = sorted(used - SERVICE_MEMBERS.keys())
assert not missing, (
f"handler 用了但未登记的成员:{missing}"
f" —— 登记进 context.SERVICE_MEMBERS,或把它改为域内模块级函数。"
)
stale = sorted(SERVICE_MEMBERS.keys() - used)
assert not stale, (
f"SERVICE_MEMBERS 里已无人使用的成员:{stale}"
f" —— 请删除,否则它对未来的越界访问就是一张免检票。"
)
# 门面对外只暴露公有名:下划线不得再穿透到业务层(G.CLS.11)。
leaked = sorted(name for name in used if name.startswith("_"))
assert not leaked, (
f"业务层直接访问了受保护成员:{['ctx.services.' + n for n in leaked]}"
f" —— 改用 SERVICE_MEMBERS 登记的公有名,私有名只应出现在 context.py 的映射里。"
)
def test_server_has_no_dangling_self_attribute_calls() -> None:
import ast
import inspect
from jiuwenswarm.server import agent_ws_server as mod
tree = ast.parse(inspect.getsource(mod))
cls = next(
n for n in ast.walk(tree)
if isinstance(n, ast.ClassDef) and n.name == "AgentWebSocketServer"
)
defined: set[str] = {
m.name for m in cls.body
if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef))
}
for node in ast.walk(cls):
# self.x = ...
if isinstance(node, ast.Assign):
for target in node.targets:
if (
isinstance(target, ast.Attribute)
and isinstance(target.value, ast.Name)
and target.value.id == "self"
):
defined.add(target.attr)
# self.x: T = ...
if (
isinstance(node, ast.AnnAssign)
and isinstance(node.target, ast.Attribute)
and isinstance(node.target.value, ast.Name)
and node.target.value.id == "self"
):
defined.add(node.target.attr)
# 类属性(含 ClassVar)
for m in cls.body:
if isinstance(m, ast.AnnAssign) and isinstance(m.target, ast.Name):
defined.add(m.target.id)
if isinstance(m, ast.Assign):
for target in m.targets:
if isinstance(target, ast.Name):
defined.add(target.id)
used = {
node.attr: node.lineno
for node in ast.walk(cls)
if isinstance(node, ast.Attribute)
and isinstance(node.value, ast.Name)
and node.value.id == "self"
}
dangling = sorted(
(lineno, name) for name, lineno in used.items() if name not in defined
)
assert not dangling, (
"以下 self.X 在类上找不到定义,运行到即 AttributeError(多半是 helper 搬走了、"
"调用方留在原地):\n "
+ "\n ".join(f"agent_ws_server.py:{ln} self.{n}" for ln, n in dangling)
)
def test_sandbox_bootstrap_helpers_callable_from_server() -> None:
from jiuwenswarm.server.agent_ws_server import AgentWebSocketServer
from jiuwenswarm.server.context import AgentServerServices
from jiuwenswarm.server.handlers.sandbox import (
allocate_internal_jiuwenbox_port,
parse_sandbox_host_port,
)
host, port = parse_sandbox_host_port("http://127.0.0.1:8321")
assert (host, port) == ("127.0.0.1", 8321)
server = AgentWebSocketServer.__new__(AgentWebSocketServer)
class _Runner:
def is_owned_listener(self, host: str, port: int) -> bool:
return True # 已拥有该监听 → 应直接复用 preferred_port
server._jiuwenbox_runner = _Runner() # type: ignore[attr-defined]
# 与 agent_ws_server._bootstrap_internal_jiuwenbox 里的调用形态完全一致
got = allocate_internal_jiuwenbox_port(AgentServerServices(server), host, port)
assert got == port, f"已拥有监听时应复用 preferred_port,实际 {got}"
# 端口被占 → 走 pick_free_tcp_port;这条同时验证门面对方法的解析
class _BusyRunner:
def is_owned_listener(self, host: str, port: int) -> bool:
return False
server._jiuwenbox_runner = _BusyRunner() # type: ignore[attr-defined]
server._is_tcp_port_bindable = lambda h, p: False # type: ignore[attr-defined]
server._pick_free_tcp_port = lambda h: 54321 # type: ignore[attr-defined]
got = allocate_internal_jiuwenbox_port(AgentServerServices(server), host, port)
assert got == 54321, f"端口被占时应改用内核分配的空闲端口,实际 {got}"