foxclaw 0.1.0 → 0.1.3

package/python/tests/test_tool_params.py

@@ -0,0 +1,99 @@
+"""M4 · 工具入参校验 + permission Stage 1 真正生效(回归)。
+
+病根(三条断链):
+  1. tools.py 构造了完整 JSON Schema,但**只发给模型**,执行侧从不校验;
+  2. base._dispatch_tool 构造 permission spec 时传 `params={}`(恒空)
+     → permission 管线 Stage 1 的必填校验**永不触发**;
+  3. model_router 解析 tool_calls 参数失败时静默替换为 `{}`
+     → 模型给了非法 JSON 也不报错,它以为工具已执行。
+
+本文件锁定:声明的 schema 在执行侧真正生效,且失败对模型可见。
+"""
+import sys
+import types
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.core.tools import default_registry, tool_capability
+from foxclaw.skills.permission import evaluate
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def main():
+    print("=" * 60)
+    print("M4 · 工具入参校验")
+    print("=" * 60)
+    r = default_registry()
+
+    print("\n【1】schema 可从注册表取到(执行侧与模型侧同一份真源)")
+    sch = r.param_schema("web_search")
+    check(bool(sch), "web_search 有 parameters schema")
+    check(sch.get("required") == ["query"], f"required 声明正确({sch.get('required')})")
+    check(bool(r.param_schema("不存在的工具") == {}), "未知工具返回空 schema(不抛异常)")
+
+    print("\n【2】必填参数缺失被检出")
+    errs = r.validate_args("web_search", {})
+    check(any("query" in e for e in errs), f"缺 query 被检出({errs})")
+    errs = r.validate_args("web_search", {"query": ""})
+    check(any("query" in e for e in errs), f"空字符串 query 也算缺失({errs})")
+
+    print("\n【3】类型不符被检出(C 类:静默失败改为可见)")
+    errs = r.validate_args("web_search", {"query": {"a": 1}})
+    check(any("类型" in e for e in errs), f"dict 传 string 位被检出({errs})")
+    errs = r.validate_args("recall_memory", {"query": "x", "top_k": "ten"})
+    check(any("类型" in e for e in errs), f"字符串传 integer 被检出({errs})")
+    errs = r.validate_args("recall_memory", {"query": "x", "top_k": True})
+    check(not any("top_k" in e for e in errs),
+          f"bool 不被误判为 integer({errs})")
+    check(r.validate_args("web_search", {"query": "ok", "未声明字段": 1}) == [],
+          "未声明的额外字段不报错(避免过度约束模型)")
+
+    print("\n【4】合法入参通过(不误拦)")
+    check(r.validate_args("web_search", {"query": "今天天气"}) == [],
+          "合法 query 无错误")
+    check(r.validate_args("recall_memory", {"query": "x", "top_k": 8}) == [],
+          "合法 top_k 无错误")
+
+    print("\n【5】permission Stage 1 真正生效(此前 params={} 恒不触发)")
+    for tool, args, want in [("web_search", {}, "ask"),
+                             ("recall_memory", {"query": "x"}, "allow")]:
+        sch_t = r.param_schema(tool)
+        req = set(sch_t.get("required") or [])
+        params = {k: {"required": k in req, "type": v.get("type")}
+                  for k, v in (sch_t.get("properties") or {}).items()
+                  if isinstance(v, dict)}
+        spec = types.SimpleNamespace(id=f"tool:{tool}", params=params,
+                                     **tool_capability(tool))
+        d = evaluate(spec, args, confirmed=False)
+        check(d.decision == want,
+              f"{tool} args={args} → {d.decision}(期望 {want})")
+        if args == {}:
+            check("缺少必填参数" in d.reason,
+                  f"Stage 1 检出缺参:{d.reason}")
+
+    print("\n【6】参数解析失败不再静默(args_parse_failed 标记存在)")
+    import inspect
+    from foxclaw.core.model_router import ModelRouter
+    src = inspect.getsource(ModelRouter)
+    check("args_parse_failed" in src,
+          "call_tools 标记解析失败(可观测)")
+    check("llm.tool_args_unparsable" in src,
+          "解析失败进 tracing(可归因)")
+
+    print("\n" + "=" * 60)
+    print("M4 全部通过")
+    print("=" * 60)
+
+
+def test_tool_params():
+    main()
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_tool_use.py

@@ -0,0 +1,229 @@
+"""
+P2 function-calling(工具化)守卫测试 —— 全离线,不打真实 LLM/网络。
+
+覆盖:
+  1. P1 运行时事实基准注入(_runtime_context / _inject_runtime 幂等)。
+  2. ToolRegistry:默认工具集、deny 过滤、tool_use 开关读 env。
+  3. ModelRouter.call_tools:不支持 tools 的 provider → supported=False(降级)。
+  4. _reply_with_tools:多轮工具循环(调用→回灌→最终答);不支持 → None(fallback)。
+  5. _dispatch_tool:web_search 命中 / 个人数据否决 / recall_memory / deny 闸。
+"""
+import os, sys, types
+from pathlib import Path
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ["FOXCLAW_EMBEDDING_MODEL"] = "foxclaw-nonexistent-fast"
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.core import tools as T
+from foxclaw.core.model_router import ModelRouter
+from foxclaw.agents.base import CognitiveAgent
+
+
+def test_runtime_context_and_idempotent():
+    r = ModelRouter(provider="stub")
+    ctx = r._runtime_context()
+    assert "运行时信息" in ctx and "模型" in ctx and "当前日期时间" in ctx
+    a = r._inject_runtime("你是助手。")
+    assert a.startswith("【运行时信息")
+    assert r._inject_runtime(a) == a, "二次注入必须幂等(防 stream→complete 重复)"
+
+
+def test_registry_default_and_deny():
+    reg = T.default_registry()
+    assert set(reg.names()) == {"web_search", "recall_memory"}
+    names = [s["function"]["name"] for s in reg.schemas()]
+    assert "web_search" in names and "recall_memory" in names
+    os.environ["FOXCLAW_TOOL_DENY"] = "web_search"
+    try:
+        names2 = [s["function"]["name"] for s in reg.schemas()]
+        assert "web_search" not in names2 and "recall_memory" in names2
+        assert T.is_tool_denied("web_search")
+    finally:
+        os.environ.pop("FOXCLAW_TOOL_DENY", None)
+
+
+def test_tool_use_flag_default_off():
+    os.environ.pop("FOXCLAW_TOOL_USE", None)
+    assert T.tool_use_enabled() is False, "默认必须关(behavior-preserving)"
+    os.environ["FOXCLAW_TOOL_USE"] = "1"
+    try:
+        assert T.tool_use_enabled() is True
+    finally:
+        os.environ.pop("FOXCLAW_TOOL_USE", None)
+
+
+def test_call_tools_unsupported_degrades():
+    r = ModelRouter(provider="stub")
+    assert r.supports_tools() is False
+    res = r.call_tools("sys", [{"role": "user", "content": "hi"}], [])
+    assert res["supported"] is False and res["tool_calls"] == []
+
+
+class _FakeRouter:
+    """脚本化 call_tools:按序返回预设结果,记录每轮 messages 长度。"""
+    def __init__(self, script):
+        self.script = list(script)
+        self.seen = []
+
+    def supports_tools(self):
+        return True
+
+    def call_tools(self, system, messages, schemas, tool_choice="auto", agent_id=""):
+        self.seen.append((tool_choice, list(messages)))
+        return self.script.pop(0)
+
+    @staticmethod
+    def format_tool_result(tc, result):
+        return {"role": "tool", "tool_call_id": tc.get("id", ""), "content": str(result)}
+
+
+def _fake_agent(router):
+    a = types.SimpleNamespace()
+    a.router = router
+    a.system_prompt = "sys"
+    a.AGENT_ID = "assistant"
+    a._dispatch_tool = lambda name, args: f"RESULT[{name}:{args.get('query','')}]"
+    return a
+
+
+def test_reply_with_tools_multi_round():
+    router = _FakeRouter([
+        {"supported": True, "text": "", "assistant_msg": {"role": "assistant", "content": ""},
+         "tool_calls": [{"id": "c1", "name": "web_search", "args": {"query": "最新模型"}}]},
+        {"supported": True, "text": "根据搜索,最新是 X。", "tool_calls": [],
+         "assistant_msg": {"role": "assistant", "content": "根据搜索,最新是 X。"}},
+    ])
+    agent = _fake_agent(router)
+    out = CognitiveAgent._reply_with_tools(agent, "有哪些新模型",
+                                           [{"role": "user", "content": "有哪些新模型"}])
+    assert out == "根据搜索,最新是 X。"
+    _, round2_msgs = router.seen[1]
+    roles = [m["role"] for m in round2_msgs]
+    assert "assistant" in roles and "tool" in roles
+    assert any("RESULT[web_search" in str(m.get("content", "")) for m in round2_msgs)
+
+
+def test_reply_with_tools_direct_answer_no_tool():
+    router = _FakeRouter([
+        {"supported": True, "text": "你好呀!", "tool_calls": [],
+         "assistant_msg": {"role": "assistant", "content": "你好呀!"}},
+    ])
+    agent = _fake_agent(router)
+    out = CognitiveAgent._reply_with_tools(agent, "你好", [{"role": "user", "content": "你好"}])
+    assert out == "你好呀!" and len(router.seen) == 1
+
+
+def test_reply_with_tools_unsupported_returns_none():
+    agent = types.SimpleNamespace(router=types.SimpleNamespace(supports_tools=lambda: False),
+                                  system_prompt="s", AGENT_ID="a")
+    out = CognitiveAgent._reply_with_tools(agent, "t", [{"role": "user", "content": "t"}])
+    assert out is None, "不支持 tools 必须返回 None 让上层 fallback"
+
+
+def test_reply_with_tools_empty_answer_returns_none():
+    router = _FakeRouter([
+        {"supported": True, "text": "", "tool_calls": [],
+         "assistant_msg": {"role": "assistant", "content": ""}},
+    ])
+    agent = _fake_agent(router)
+    out = CognitiveAgent._reply_with_tools(agent, "你好", [{"role": "user", "content": "你好"}])
+    assert out is None, "空答必须返回 None 让上层 fallback"
+
+
+def test_dispatch_web_search_ok(monkeypatch):
+    from foxclaw.core import web_search as ws
+    monkeypatch.setattr(ws, "search_answer", lambda q: {"answer": "实时答案XYZ", "references": []})
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "OpenAI 新模型"})
+    assert "实时答案XYZ" in out
+
+
+def test_dispatch_web_search_personal_veto():
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "我本月支出多少"})
+    assert "本地" in out, "私人财务问题不得外发联网"
+
+
+def test_dispatch_recall_memory():
+    agent = types.SimpleNamespace(
+        _recall_memory=lambda q, top_k=5: [{"content": "用户喜欢灰色"}])
+    out = CognitiveAgent._dispatch_tool(agent, "recall_memory", {"query": "颜色偏好"})
+    assert "灰色" in out
+
+
+def test_dispatch_denied(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_TOOL_DENY", "web_search")
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "x"})
+    assert "禁用" in out
+
+
+def test_tool_capability_readonly_and_failclosed():
+    assert T.tool_capability("web_search")["read_only"] is True
+    assert T.tool_capability("recall_memory")["side_effect"] == "read"
+    cap = T.tool_capability("some_future_write_tool")
+    assert cap["read_only"] is False and cap["side_effect"] == "write" and cap["external"] is True
+
+
+def test_permission_gate_allows_readonly_asks_sideeffect():
+    import types as _t
+    from foxclaw.skills import permission as perm
+    ro = _t.SimpleNamespace(id="tool:web_search", params={}, **T.tool_capability("web_search"))
+    assert perm.evaluate(ro, {}, confirmed=False).decision == "allow"
+    send = _t.SimpleNamespace(id="tool:send_email", params={},
+                              side_effect="send", read_only=False, external=True, destructive=False)
+    d = perm.evaluate(send, {}, confirmed=False)
+    assert d.decision == "ask" and d.requires_confirmation
+
+
+def test_dispatch_hitl_blocks_side_effect_tool(monkeypatch):
+    """核心:若工具被判为有副作用(写/发送),_dispatch_tool 走 HITL——不执行、返回需确认。"""
+    from foxclaw.core import web_search as ws
+    called = {"n": 0}
+    monkeypatch.setattr(ws, "search_answer",
+                        lambda q: called.__setitem__("n", called["n"] + 1) or {"answer": "x"})
+    monkeypatch.setattr(T, "tool_capability",
+                        lambda name: {"side_effect": "send", "read_only": False,
+                                      "external": True, "destructive": False})
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "x"})
+    assert "确认" in out and called["n"] == 0, "有副作用工具必须 HITL、不自动执行"
+
+
+def test_dispatch_unknown_tool():
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "nonexistent_tool", {"x": 1})
+    assert "未知工具" in out
+
+
+def test_tool_path_injects_preferences(monkeypatch):
+    """回归(Finding 1):工具路径也要注入用户偏好,不能开工具化就丢掉"越用越懂你"。"""
+    monkeypatch.setenv("FOXCLAW_TOOL_USE", "1")
+    captured = {}
+    fake = types.SimpleNamespace()
+    fake._sanitize_history = lambda h, max_turns=12: []
+    fake.router = types.SimpleNamespace(supports_tools=lambda: True)
+    fake.AGENT_ID = "assistant"
+    fake._ability_augment = lambda t, m: m
+    fake._skill_augment = lambda t, m: m
+    fake._pref_augment = lambda m: (list(m[:-1]) +
+        [{"role": "user", "content": "【用户偏好】喜欢简洁\n\n" + m[-1]["content"]}])
+
+    def _rwt(task, messages, stop_event=None):
+        captured["msgs"] = messages
+        return "好的,已处理。"
+    fake._reply_with_tools = _rwt
+    fake._think = lambda **k: None
+    fake._store_memory = lambda *a, **k: None
+    fake._maybe_store_preference = lambda t: None
+
+    out = "".join(CognitiveAgent.stream_reply(fake, "帮我总结这段"))
+    assert "已处理" in out
+    assert any("喜欢简洁" in str(x.get("content", "")) for x in captured["msgs"]), \
+        "工具路径必须注入用户偏好(Finding 1)"
+
+
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__, "-v"])

package/python/tests/test_toplevel_concurrency.py

@@ -0,0 +1,116 @@
+"""
+顶层任务并发隔离回归（per-task 会话状态 via contextvars）
+
+背景:FastAPI 多个并发请求跑在同一事件循环、可能打到同一 Agent 实例。旧实现把
+_session_id/_parent_node_id/harness._baseline 存在实例上,await 之后的推理节点会被
+"最后启动的会话"吞掉(实测分布 [2×7,10])。改为 contextvar 承载后各任务隔离。
+
+验证:
+  1. 同一 Agent 实例并发 N 个顶层任务 → 每会话节点数均衡、无跨会话父链接、goal 归属正确;
+  2. 主管并发处理不同领域任务 → 各自分诊正确、会话不串。
+"""
+import asyncio
+import json
+import sqlite3
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import foxclaw.core.web_search as ws
+ws.needs_search = lambda q: False
+
+from foxclaw import Foxclaw
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def _slow(system, messages, max_tokens=2048, agent_id=""):
+    time.sleep(0.1)
+    return "ok"
+
+
+def _build(data_dir=None):
+    os_ = Foxclaw(data_dir=data_dir or tempfile.mkdtemp())
+    os_.router.complete = _slow
+    return os_
+
+
+@pytest.fixture(scope="module")
+def os_(tmp_path_factory):
+    """共享同一 Foxclaw 实例(等价脚本式 main() 里 `os_ = _build()` 一次传给 2 个测试)。"""
+    return _build(data_dir=str(tmp_path_factory.mktemp("toplevel_concurrency")))
+
+
+def test_same_instance_concurrent(os_):
+    print("\n【1】同一 Agent 实例并发 8 个顶层任务:无串味")
+    office = os_.office
+    N = 8
+    tasks = [f"学习任务 MARK{i:02d} 请总结" for i in range(N)]
+
+    async def run():
+        return await asyncio.gather(*[office.run_task(t) for t in tasks])
+    res = asyncio.run(run())
+
+    tc = os_.thought_chain
+    con = sqlite3.connect(tc.db_path)
+    rows = con.execute("SELECT id,session_id,parent_ids FROM thought_nodes "
+                       "WHERE agent_id='office'").fetchall()
+    sid_of = {r[0]: r[1] for r in rows}
+    per = {}
+    for _id, sid, _p in rows:
+        per[sid] = per.get(sid, 0) + 1
+    cross = sum(1 for _id, sid, p in rows for par in json.loads(p)
+                if par in sid_of and sid_of[par] != sid)
+    ok_goal = 0
+    for i, r in enumerate(res):
+        g = con.execute("SELECT content FROM thought_nodes WHERE session_id=? "
+                        "AND type='goal'", (r["session_id"],)).fetchall()
+        if g and f"MARK{i:02d}" in g[0][0]:
+            ok_goal += 1
+
+    check(len(per) == N, f"产生 {N} 个独立会话")
+    check(len(set(per.values())) == 1, f"每会话节点数均衡(无坍缩): {sorted(per.values())}")
+    check(cross == 0, "无跨会话父链接(推理链未错连)")
+    check(ok_goal == N, f"每个会话的 goal 归属正确: {ok_goal}/{N}")
+
+
+def test_supervisor_concurrent(os_):
+    print("\n【2】主管并发处理不同领域任务:分诊正确、会话不串")
+    sup = os_.supervisor
+
+    async def run():
+        return await asyncio.gather(
+            sup.run_task("分析本月理财预算"),
+            sup.run_task("总结这篇论文的要点"),
+            sup.run_task("你能做什么"),
+        )
+    res = asyncio.run(run())
+    routed = [r["result"].get("dispatched_to") for r in res]
+    sids = [r["session_id"] for r in res]
+    check(routed == ["finance", "office", "supervisor"], f"三个并发任务分诊各就各位: {routed}")
+    check(len(set(sids)) == 3, "三个任务会话 id 互不相同(未串会话)")
+
+
+def main():
+    print("=" * 56)
+    print("顶层任务并发隔离回归")
+    print("=" * 56)
+    os_ = _build()
+    for t in (test_same_instance_concurrent, test_supervisor_concurrent):
+        t(os_)
+    print("\n" + "=" * 56)
+    print("顶层并发隔离通过")
+    print("=" * 56)
+
+
+if __name__ == "__main__":
+    main()