procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/webplatform/aat_mcp/tests/test_aat_mcp.py

@@ -0,0 +1,255 @@
+"""Tests for the aat-mcp bridge + stdio JSON-RPC server + reversibility gate.
+
+Protocol dispatch, the reversibility gate, and the anti-thrash argv guarantee are
+tested with fakes - no real subprocess, no credential access.
+"""
+from __future__ import annotations
+
+import json
+
+import bridge
+import gate
+import server
+
+
+def _call(name, arguments, _id=1):
+    return server.handle({"jsonrpc": "2.0", "id": _id, "method": "tools/call",
+                          "params": {"name": name, "arguments": arguments}})
+
+
+# --- protocol dispatch ---------------------------------------------------
+
+def test_initialize_echoes_protocol_and_serverinfo():
+    resp = server.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                          "params": {"protocolVersion": "2024-11-05"}})
+    assert resp["result"]["serverInfo"]["name"] == "aat-mcp"
+    assert resp["result"]["protocolVersion"] == "2024-11-05"
+    assert "tools" in resp["result"]["capabilities"]
+
+
+def test_initialize_defaults_protocol_when_absent():
+    resp = server.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                          "params": {}})
+    assert resp["result"]["protocolVersion"] == server.DEFAULT_PROTOCOL
+
+
+def test_notifications_get_no_response():
+    assert server.handle({"jsonrpc": "2.0", "method": "notifications/initialized"}) is None
+    assert server.handle({"jsonrpc": "2.0", "method": "notifications/cancelled"}) is None
+
+
+def test_ping():
+    assert server.handle({"jsonrpc": "2.0", "id": 7, "method": "ping"})["result"] == {}
+
+
+def test_tools_list_exposes_the_six_tools():
+    resp = server.handle({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+    names = {t["name"] for t in resp["result"]["tools"]}
+    assert names == {"capabilities", "run_tool", "run_tool_confirmed",
+                     "run_agent", "run_agent_confirmed", "get_skill"}
+    assert all("inputSchema" in t for t in resp["result"]["tools"])
+
+
+def test_unknown_method_is_jsonrpc_error():
+    resp = server.handle({"jsonrpc": "2.0", "id": 9, "method": "does/not/exist"})
+    assert resp["error"]["code"] == -32601
+
+
+def test_unknown_notification_is_swallowed():
+    assert server.handle({"jsonrpc": "2.0", "method": "does/not/exist"}) is None
+
+
+# --- reversibility gate --------------------------------------------------
+
+def test_reversible_action_runs_on_plain_tool(monkeypatch):
+    called = {}
+    monkeypatch.setattr(server.bridge, "run_tool",
+                        lambda t, a, args: called.update(t=t, a=a) or
+                        {"ok": True, "data": {"x": 1}, "error": None})
+    resp = _call("run_tool", {"tool": "google-mail", "action": "list-messages"})
+    assert resp["result"]["isError"] is False
+    assert called == {"t": "google-mail", "a": "list-messages"}
+
+
+def test_irreversible_action_refused_on_plain_tool(monkeypatch):
+    # bridge.run_tool must NOT be called - the gate refuses before execution.
+    monkeypatch.setattr(server.bridge, "run_tool",
+                        lambda *a, **k: (_ for _ in ()).throw(AssertionError("executed!")))
+    resp = _call("run_tool", {"tool": "google-mail", "action": "send-message",
+                              "args": {"to": "a@example.com"}})
+    payload = json.loads(resp["result"]["content"][0]["text"])
+    assert "approval_required" in payload
+    assert payload["approval_required"]["verb"] == "send"
+    assert payload["approval_required"]["blast_class"] == "message-sent"
+    assert "run_tool_confirmed" in payload["approval_required"]["next"]
+
+
+def test_irreversible_action_runs_on_confirmed_tool(monkeypatch):
+    called = {}
+    monkeypatch.setattr(server.bridge, "run_tool",
+                        lambda t, a, args: called.update(t=t, a=a, args=args) or
+                        {"ok": True, "data": {"id": "m1"}, "error": None})
+    resp = _call("run_tool_confirmed", {"tool": "google-mail", "action": "send-message",
+                                        "args": {"to": "a@example.com"}})
+    assert resp["result"]["isError"] is False
+    assert called["t"] == "google-mail" and called["a"] == "send-message"
+
+
+def test_confirmed_denied_when_headless_env_set(monkeypatch):
+    monkeypatch.setattr(gate, "deny_irreversible_env", lambda: True)
+    monkeypatch.setattr(server.bridge, "run_tool",
+                        lambda *a, **k: (_ for _ in ()).throw(AssertionError("executed!")))
+    resp = _call("run_tool_confirmed", {"tool": "google-mail", "action": "send-message"})
+    assert resp["result"]["isError"] is True
+    payload = json.loads(resp["result"]["content"][0]["text"])
+    assert "refused" in payload
+
+
+def test_agent_intake_is_reversible_and_runs(monkeypatch):
+    called = {}
+    monkeypatch.setattr(server.bridge, "run_agent",
+                        lambda ag, a, args: called.update(ag=ag, a=a) or
+                        {"ok": True, "data": {}, "error": None})
+    resp = _call("run_agent", {"agent": "orchestrator", "action": "intake",
+                               "args": {"request": "collect invoices"}})
+    assert resp["result"]["isError"] is False
+    assert called == {"ag": "orchestrator", "a": "intake"}
+
+
+def test_run_tool_requires_tool_arg():
+    resp = _call("run_tool", {})
+    assert resp["result"]["isError"] is True
+
+
+def test_call_unknown_tool_is_error():
+    resp = _call("nope", {})
+    assert resp["result"]["isError"] is True
+
+
+def test_get_skill_keyerror_becomes_readable_error(monkeypatch):
+    def boom(name):
+        raise KeyError("skill not found: ghost")
+    monkeypatch.setattr(server.bridge, "get_skill", boom)
+    resp = _call("get_skill", {"name": "ghost"})
+    assert resp["result"]["isError"] is True
+    assert "ghost" in resp["result"]["content"][0]["text"]
+
+
+# --- gate classifier -----------------------------------------------------
+
+def test_gate_classify_verbs():
+    assert gate.classify("google-mail", "send-message")["reversible"] is False
+    assert gate.classify("whatsapp-personal", "delete-messages")["reversible"] is False
+    assert gate.classify("fgo", "issue-invoice")["reversible"] is False
+    assert gate.classify("google-mail", "list-messages")["reversible"] is True
+    assert gate.classify("apollo", "search-people")["reversible"] is True
+    assert gate.classify("hello-world", None)["reversible"] is True
+
+
+def test_gate_ignores_arg_values_only_action_and_name():
+    # The gate classifies on name + action, never arg values - so a subject line
+    # that contains "send" does not trip it (that is the caller's job to pass action).
+    assert gate.classify("google-mail", "create-draft")["reversible"] is True
+
+
+# --- the anti-thrash guarantee ------------------------------------------
+
+def test_bridge_encodes_json_args_as_single_argv_element(monkeypatch):
+    seen = {}
+
+    def fake_run_tool(tool, argv, **k):
+        seen.update(tool=tool, argv=argv)
+        return {"ok": True, "data": {}, "error": None}
+
+    monkeypatch.setattr(bridge.runner, "run_tool", fake_run_tool)
+    bridge.run_tool("google-mail", "send-message",
+                    {"to": "a@example.com", "cc": ["x@example.com", "z@example.com"]})
+    assert seen["argv"][0] == "send-message"
+    i = seen["argv"].index("--cc")
+    assert json.loads(seen["argv"][i + 1]) == ["x@example.com", "z@example.com"]
+
+
+def test_bridge_omits_action_for_flat_tool(monkeypatch):
+    seen = {}
+    monkeypatch.setattr(bridge.runner, "run_tool",
+                        lambda tool, argv, **k: seen.update(argv=argv) or
+                        {"ok": True, "data": {}, "error": None})
+    bridge.run_tool("hello-world", None, {"name": "Z"})
+    assert seen["argv"] == ["--name", "Z"]
+
+
+# --- host-only delegation (host-side tool-runner) ------------------------
+
+def test_is_host_only_detects_listed_vs_plain():
+    assert bridge._is_host_only("tool", "web") is True    # listed: drives a real browser profile
+    assert bridge._is_host_only("tool", "xlsx") is False  # neither listed nor web_session
+
+
+def test_run_tool_delegates_host_only_when_runner_set(monkeypatch):
+    seen = {}
+    monkeypatch.setenv("AAT_HOST_RUNNER_URL", "http://host.docker.internal:8904")
+    monkeypatch.setattr(bridge, "_delegate",
+                        lambda kind, name, action, args: seen.update(kind=kind, name=name) or
+                        {"ok": True, "data": {"delegated": True}})
+    monkeypatch.setattr(bridge.runner, "run_tool",
+                        lambda *a, **k: (_ for _ in ()).throw(AssertionError("ran locally!")))
+    r = bridge.run_tool("web", "get-text", {"url": "https://example.com"})
+    assert r["data"]["delegated"] is True
+    assert seen == {"kind": "tool", "name": "web"}
+
+
+def test_run_tool_runs_locally_when_not_host_only(monkeypatch):
+    monkeypatch.setenv("AAT_HOST_RUNNER_URL", "http://host.docker.internal:8904")
+    monkeypatch.setattr(bridge.runner, "run_tool",
+                        lambda tool, argv, **k: {"ok": True, "data": {"local": tool}})
+    monkeypatch.setattr(bridge, "_delegate",
+                        lambda *a, **k: (_ for _ in ()).throw(AssertionError("delegated!")))
+    assert bridge.run_tool("hello-world", None, {"name": "X"})["data"]["local"] == "hello-world"
+
+
+def test_no_delegation_without_runner_url(monkeypatch):
+    monkeypatch.delenv("AAT_HOST_RUNNER_URL", raising=False)
+    monkeypatch.setattr(bridge.runner, "run_tool",
+                        lambda tool, argv, **k: {"ok": True, "data": {"local": True}})
+    # a host-only tool still runs locally when no host-runner is configured (local platform)
+    assert bridge.run_tool("whatsapp-personal", "list-chats", {})["data"]["local"] is True
+
+
+# --- tool annotations ----------------------------------------------------
+
+def test_every_tool_declares_a_title_and_hints():
+    """A directory listing requires both, and a client uses them for permissions."""
+    for t in server.TOOLS:
+        assert t.get("title"), f"{t['name']} has no title"
+        a = t.get("annotations") or {}
+        assert a.get("title") == t["title"]
+        for hint in ("readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"):
+            assert isinstance(a.get(hint), bool), f"{t['name']} missing {hint}"
+        assert len(t["name"]) <= 64
+
+
+def test_a_tool_that_dispatches_arbitrary_actions_is_never_read_only():
+    """The rule that stops a write from running unprompted.
+
+    A readOnlyHint tool may be run by a client WITHOUT asking. Anything that takes a
+    caller-supplied action and forwards it can reach a create or an update, so it can
+    never make that claim. The check reads the input schema rather than a list of
+    names, so a dispatcher added later is caught without anyone remembering to add it.
+    """
+    for t in server.TOOLS:
+        props = set(((t.get("inputSchema") or {}).get("properties") or {}))
+        dispatches = "action" in props and bool(props & {"tool", "agent"})
+        if dispatches:
+            a = t["annotations"]
+            assert a["readOnlyHint"] is False, (
+                f"{t['name']} forwards a caller-supplied action and claims readOnlyHint")
+            assert a["destructiveHint"] is True
+
+
+def test_a_freeform_dispatcher_names_the_api_it_targets():
+    """Required of any tool whose caller constructs the request."""
+    for t in server.TOOLS:
+        props = set(((t.get("inputSchema") or {}).get("properties") or {}))
+        if "action" in props and "tool" in props:
+            assert "procesio.com" in t["description"], (
+                f"{t['name']} accepts freeform actions but names no API")

procesio_cli/webplatform/aat_mcp/tests/test_chat_surface.py

@@ -0,0 +1,247 @@
+"""The three gates that keep the published chat surface and the framework independent.
+
+chat_surface.yaml declares what is published; the registry remains the source of truth
+for what exists. They are allowed to drift - that is the point of having two of them -
+but never silently, and never past CI.
+
+    1. conformance  every declared target/argument still exists and still means the
+                    same thing. Catches a renamed action, a retyped argument and, most
+                    quietly of all, a NEW required argument on an action we already
+                    publish - which breaks nothing until a user's first call.
+    2. snapshot     the exact tools/list payload is checked in, so any change to the
+                    published contract arrives as a reviewable diff instead of a
+                    surprise in a directory listing. MCP clients cache tool definitions
+                    at initialisation and do not refresh them, so a schema that changes
+                    under a client does not error - it misleads.
+    3. isolation    neither surface imports the other, and the published one reaches
+                    only the shared substrate.
+
+Regenerating the snapshot after a deliberate change:
+    python -c "import sys; sys.path.insert(0,'webplatform/aat_mcp'); \
+import json, chat_server as c; \
+open('webplatform/aat_mcp/chat_surface.snapshot.json','w',newline='\\n').write( \
+json.dumps(c.build_tools(c.load_surface()), indent=2, ensure_ascii=False)+'\\n')"
+"""
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+import bridge  # noqa: F401  - puts the repo root on sys.path for `registry`
+import chat_server
+import gate
+import registry
+import server
+
+_HERE = Path(__file__).resolve().parents[1]
+SNAPSHOT = _HERE / "chat_surface.snapshot.json"
+
+
+def _registry_index():
+    tools = {t["name"]: t for t in registry.list_tools()}
+    agents = {a["name"]: a for a in registry.list_agents(tools)}
+    return tools, agents
+
+
+def _resolve(spec):
+    """(entry, action_dict) for a declared tool, or (None, None)."""
+    tools, agents = _registry_index()
+    target = spec["target"]
+    who = target.get("tool") or target.get("agent")
+    entry = (tools if "tool" in target else agents).get(who)
+    if entry is None:
+        return None, None
+    action = {a["name"]: a for a in (entry.get("actions") or [])}.get(target.get("action"))
+    return entry, action
+
+
+# --- gate 1: conformance -------------------------------------------------
+
+def test_every_declared_target_still_exists():
+    missing = []
+    for spec in chat_server.SURFACE["tools"]:
+        entry, action = _resolve(spec)
+        if entry is None or action is None:
+            missing.append(f"{spec['name']} -> {spec['target']}")
+    assert not missing, (
+        "declared in chat_surface.yaml but not in the registry (an action was renamed "
+        f"or removed; update the declaration deliberately): {missing}")
+
+
+def test_every_declared_argument_still_exists_with_the_declared_type():
+    problems = []
+    for spec in chat_server.SURFACE["tools"]:
+        _, action = _resolve(spec)
+        if action is None:
+            continue
+        manifest = {a["name"]: a for a in action["args"]}
+        declared = list(spec.get("args") or [])
+        declared += [chat_server.SURFACE["common_args"][k] for k in (spec.get("common") or [])]
+        for arg in declared:
+            flag = arg["flag"]
+            if flag not in manifest:
+                problems.append(f"{spec['name']}: --{flag} no longer exists")
+                continue
+            want, got = arg.get("type"), manifest[flag].get("type")
+            if want and got and want != got:
+                problems.append(f"{spec['name']}: --{flag} is {got}, declared {want}")
+    assert not problems, problems
+
+
+def test_no_required_argument_is_left_undeclared():
+    """The silent one. A new required argument on an action we already publish leaves
+    the published schema valid and every call failing, because the surface has no way
+    to supply it. It has to fail here instead."""
+    problems = []
+    for spec in chat_server.SURFACE["tools"]:
+        _, action = _resolve(spec)
+        if action is None:
+            continue
+        exposed = {a["flag"] for a in (spec.get("args") or [])}
+        exposed |= {chat_server.SURFACE["common_args"][k]["flag"]
+                    for k in (spec.get("common") or [])}
+        for arg in action["args"]:
+            if arg.get("required") and arg["name"] not in exposed and arg.get("default") is None:
+                problems.append(f"{spec['name']}: --{arg['name']} is required by "
+                                f"{spec['target']} but the surface cannot supply it")
+    assert not problems, problems
+
+
+def test_no_published_tool_reaches_an_irreversible_action():
+    """This surface has no confirmed-twin path, so it must carry nothing that needs one.
+    Adding a destructive action fails the build rather than growing a second, softer
+    approval route beside the one in server.py."""
+    bad = []
+    for spec in chat_server.SURFACE["tools"]:
+        t = spec["target"]
+        verdict = gate.classify(t.get("tool") or t.get("agent"), t.get("action"))
+        if not verdict["reversible"]:
+            bad.append(f"{spec['name']} ({verdict['verb']}/{verdict['blast_class']})")
+    assert not bad, bad
+
+
+def test_read_only_entries_are_also_reversible():
+    """read_only and reversible are different questions - process-create is reversible
+    and is not read-only - but the implication holds one way: a call that changes
+    nothing cannot be irreversible. A mislabel here would let a write run unattended."""
+    for spec in chat_server.SURFACE["tools"]:
+        if not spec["read_only"]:
+            continue
+        t = spec["target"]
+        verdict = gate.classify(t.get("tool") or t.get("agent"), t.get("action"))
+        assert verdict["reversible"], f"{spec['name']} claims read_only but the gate disagrees"
+
+
+def test_excluded_operations_are_not_also_published():
+    """The exclusion list is part of the contract. An entry that reappears in `tools`
+    means someone reversed a decision without reading why it was made."""
+    published = {(s["target"].get("tool") or s["target"].get("agent"), s["target"].get("action"))
+                 for s in chat_server.SURFACE["tools"]}
+    for item in chat_server.SURFACE["excluded"]:
+        target = item["target"]
+        if "*" in target or "<" in target or " " in target:
+            continue  # a class of actions or an argument, not one target
+        who, _, action = target.partition("/")
+        assert (who, action) not in published, f"{target} is both excluded and published"
+        assert item.get("reason", "").strip(), f"{target} is excluded with no reason"
+
+
+# --- gate 2: snapshot ----------------------------------------------------
+
+def test_published_surface_matches_the_checked_in_snapshot():
+    built = chat_server.build_tools(chat_server.load_surface())
+    saved = json.loads(SNAPSHOT.read_text(encoding="utf-8"))
+    assert built == saved, (
+        "the published tool list changed. If that was intended, regenerate the snapshot "
+        "(command in this module's docstring), bump surface_version, and let the diff be "
+        "reviewed - a client caches these definitions and will not notice on its own.")
+
+
+def test_snapshot_is_the_shape_a_client_receives():
+    saved = json.loads(SNAPSHOT.read_text(encoding="utf-8"))
+    listed = chat_server.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/list"})
+    assert listed["result"]["tools"] == saved
+
+
+# --- gate 3: isolation ---------------------------------------------------
+
+def _imports(path: Path) -> set[str]:
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            names |= {a.name.split(".")[0] for a in node.names}
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            names.add(node.module.split(".")[0])
+    return names
+
+
+def test_the_two_surfaces_do_not_import_each_other():
+    assert "server" not in _imports(_HERE / "chat_server.py")
+    assert "chat_server" not in _imports(_HERE / "server.py")
+
+
+def test_the_shared_protocol_module_imports_neither_surface():
+    """protocol.py is shared so that negotiation has ONE implementation - two copies are how
+    both servers came to agree to any version asked for. It must stay below both surfaces:
+    if it imported one, a change to that surface would reach the other through it."""
+    assert not _imports(_HERE / "protocol.py") & {"server", "chat_server", "bridge", "gate"}
+
+
+def test_the_published_surface_reaches_only_the_shared_substrate():
+    """Whatever this surface imports is what a change elsewhere can reach it through.
+    Keeping the list short is the isolation; asserting it is what keeps it short."""
+    allowed = {"bridge", "gate", "protocol", "yaml", "json", "os", "sys", "pathlib", "__future__"}
+    assert _imports(_HERE / "chat_server.py") <= allowed
+
+
+def test_a_tool_that_dispatches_arbitrary_actions_is_never_read_only():
+    """Applied across BOTH surfaces, and derived from the schema rather than a list of
+    names, so a dispatcher added later is caught without anyone remembering this rule."""
+    for tools in (server.TOOLS, chat_server.TOOLS):
+        for t in tools:
+            props = set(((t.get("inputSchema") or {}).get("properties") or {}))
+            if "action" in props and props & {"tool", "agent"}:
+                a = t["annotations"]
+                assert a["readOnlyHint"] is False, t["name"]
+                assert a["destructiveHint"] is True, t["name"]
+
+
+# --- the surface as a client sees it -------------------------------------
+
+def test_initialize_reports_the_surface_version():
+    resp = chat_server.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                               "params": {"protocolVersion": "2024-11-05"}})
+    info = resp["result"]["serverInfo"]
+    assert info["name"] == "procesio-chat"
+    assert info["version"] == chat_server.SURFACE["surface_version"]
+
+
+def test_every_published_tool_is_named_for_its_domain():
+    """Namespacing: a directory client merges several servers' tools into one list, so a
+    bare `create_process` competes with every other automation product's."""
+    for t in chat_server.TOOLS:
+        assert t["name"].startswith("procesio_"), t["name"]
+        assert t["title"] and t["description"], t["name"]
+
+
+def test_no_published_tool_accepts_an_undeclared_argument():
+    """The schema is the contract. An argument the declaration does not name is dropped
+    rather than forwarded, so a caller cannot reach past the published surface."""
+    spec = chat_server._BY_NAME["procesio_list_processes"]
+    by_exposed = {chat_server.exposed_name(a) for a in spec["args"]}
+    assert "profile" not in by_exposed  # a local installation detail, deliberately unexposed
+
+
+def test_unknown_tool_is_an_error_payload_not_a_crash():
+    payload, is_error = chat_server.call_tool("procesio_not_a_tool", {})
+    assert is_error and "unknown tool" in payload["error"]
+
+
+def test_an_oversized_result_is_capped_with_an_actionable_hint():
+    spec = chat_server._BY_NAME["procesio_list_processes"]
+    capped = chat_server._cap({"ok": True, "rows": ["x" * 100] * 2000}, spec)
+    assert capped["truncated"] is True
+    assert "search" in capped["hint"]  # names the argument that narrows THIS tool
+    assert len(capped["preview"]) <= 2000