procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/webplatform/aat_mcp/protocol.py

@@ -0,0 +1,175 @@
+"""MCP protocol mechanics shared by both surfaces: version negotiation and the 2026-07-28 era.
+
+The two servers publish different tools for different audiences and stay independent of each
+other (neither imports the other; tests/test_chat_surface.py asserts it). The protocol they
+speak is a different matter. It has one correct behaviour, and keeping a copy of it in each
+server is how both came to agree to any protocol version a client asked for, including ones
+that do not exist. So the mechanics live here, once. Each server supplies only what is its
+own: its tools, its dispatcher and its identity.
+
+MCP's own terms for the two eras:
+
+  legacy  2025-11-25 and earlier. An `initialize` handshake fixes the version for the process.
+  modern  2026-07-28. No handshake: every request carries its version in `_meta`, every result
+          carries `resultType`, list results carry `ttlMs` and `cacheScope`, and servers MUST
+          implement `server/discover`.
+
+A server that speaks both is "dual-era". Both servers are dual-era over stdio, because a
+modern-only stdio server would fail every legacy client, and legacy clients have no way to
+fall forward.
+
+The HTTP transport calls ``handle(..., modern=False)``. Modern Streamable HTTP adds header
+rules (`Mcp-Method`, `Mcp-Name`) that transport does not implement, so it must not advertise
+the modern era. Over it, `server/discover` stays a plain method-not-found: that is the answer a
+dual-era client reads as "legacy server, fall back". Never answer it with a version-gated
+message instead; one public MCP server did, and the client took it as a modern reply and
+stopped seeing its tools.
+
+Pure standard library, so either server can import it without widening what it depends on.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from typing import Callable
+
+MODERN_VERSIONS = ("2026-07-28",)
+# Newest first. A tools-only server meets every one of these: later revisions only ADD
+# optional fields (annotations, title, outputSchema), which earlier clients ignore.
+LEGACY_VERSIONS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+
+META_VERSION = "io.modelcontextprotocol/protocolVersion"
+META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
+META_TOOLS_DIGEST = "com.procesio/toolsDigest"
+
+PARSE_ERROR = -32700
+METHOD_NOT_FOUND = -32601
+INTERNAL_ERROR = -32603
+UNSUPPORTED_PROTOCOL_VERSION = -32022
+
+# The tool list cannot change while the process runs: it is built once at import and
+# `listChanged` is false. So a long freshness hint is honest, and "public" is too, because
+# the list carries no per-user data a shared intermediary should keep to itself.
+LIST_TTL_MS = 3_600_000
+CACHE_SCOPE = "public"
+
+
+def negotiate_legacy(requested) -> str:
+    """The version to answer `initialize` with: the client's if we serve it, else our newest.
+
+    `initialize` always selects the legacy era, so a client asking for a modern version there
+    gets the newest legacy one. That is what a dual-era server is required to do, and it is
+    the answer that keeps a client from expecting fields this era never sends."""
+    return requested if requested in LEGACY_VERSIONS else LEGACY_VERSIONS[0]
+
+
+def tools_digest(tools) -> str:
+    """sha256 over the canonical JSON of a `tools/list` tools array.
+
+    Canonical means keys sorted, no whitespace, UTF-8, non-ASCII left unescaped. A client or
+    gateway reproduces it from the list it actually RECEIVED and compares it with the value
+    published in server.json, which the MCP Registry does not let anyone change after
+    publication. The value a server reports about itself is a convenience for spotting which
+    release you are talking to, not a control: the spec says self-reported server information
+    must not drive security decisions."""
+    raw = json.dumps(tools, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return "sha256:" + hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def handle(req: dict, *, tools: list, call_tool: Callable[[str, dict], tuple[dict, bool]],
+           server_info: dict, modern: bool = True) -> dict | None:
+    """Dispatch one JSON-RPC request. Returns a response, or None for a notification."""
+    method = req.get("method") or ""
+    req_id = req.get("id")
+    is_notification = "id" not in req
+    params = req.get("params") if isinstance(req.get("params"), dict) else {}
+    meta = params.get("_meta")
+    requested = meta.get(META_VERSION) if isinstance(meta, dict) else None
+    is_modern = modern and requested is not None
+
+    def ok(result):
+        return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+    def err(code, message, data=None):
+        error = {"code": code, "message": message}
+        if data is not None:
+            error["data"] = data
+        return {"jsonrpc": "2.0", "id": req_id, "error": error}
+
+    def complete(result, *, cacheable=False):
+        """Modern results carry resultType and the server's identity; lists add cache hints."""
+        result = dict(result)
+        result["resultType"] = "complete"
+        result["_meta"] = {**(result.get("_meta") or {}), META_SERVER_INFO: server_info}
+        if cacheable:
+            result["ttlMs"] = LIST_TTL_MS
+            result["cacheScope"] = CACHE_SCOPE
+        return ok(result)
+
+    if method.startswith("notifications/"):
+        return None
+
+    if is_modern and requested not in MODERN_VERSIONS:
+        if is_notification:
+            return None
+        # A recognised modern error: it tells a dual-era client this server IS modern, so it
+        # retries with a listed version instead of falling back to `initialize`.
+        return err(UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version",
+                   {"supported": list(MODERN_VERSIONS), "requested": requested})
+
+    if method == "server/discover":
+        if not modern:
+            return err(METHOD_NOT_FOUND, f"method not found: {method}")
+        return complete({"supportedVersions": list(MODERN_VERSIONS),
+                         "capabilities": {"tools": {}},
+                         "_meta": {META_TOOLS_DIGEST: tools_digest(tools)}}, cacheable=True)
+
+    if method == "initialize":
+        return ok({"protocolVersion": negotiate_legacy(params.get("protocolVersion")),
+                   "capabilities": {"tools": {"listChanged": False}},
+                   "serverInfo": server_info})
+
+    if method == "ping":  # removed in the modern era; harmless to keep answering for legacy
+        return ok({})
+
+    if method == "tools/list":
+        return complete({"tools": tools}, cacheable=True) if is_modern else ok({"tools": tools})
+
+    if method == "tools/call":
+        payload, is_error = call_tool(params.get("name", ""), params.get("arguments") or {})
+        result = {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False)}],
+                  "isError": is_error}
+        return complete(result) if is_modern else ok(result)
+
+    if is_notification:
+        return None
+    return err(METHOD_NOT_FOUND, f"method not found: {method}")
+
+
+def serve_stdio(handle_fn: Callable[[dict], dict | None], log: Callable[[str], None]) -> None:
+    """Newline-delimited JSON-RPC over stdin/stdout. Never raises out of the loop."""
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", newline="\n")
+        sys.stdin.reconfigure(encoding="utf-8")
+    except Exception:  # noqa: BLE001 - older interpreters; best effort
+        pass
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except ValueError:
+            resp = {"jsonrpc": "2.0", "id": None,
+                    "error": {"code": PARSE_ERROR, "message": "parse error"}}
+        else:
+            try:
+                resp = handle_fn(req)
+            except Exception as e:  # noqa: BLE001
+                log(f"handler error: {e}")
+                resp = {"jsonrpc": "2.0", "id": req.get("id") if isinstance(req, dict) else None,
+                        "error": {"code": INTERNAL_ERROR, "message": f"internal error: {e}"}}
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
+            sys.stdout.flush()

procesio_cli/webplatform/aat_mcp/server.py

@@ -0,0 +1,306 @@
+"""aat-mcp: a stdio MCP server exposing the AAT registry as a small generic surface.
+
+Hand-rolled JSON-RPC 2.0 over newline-delimited stdio (no third-party dependency,
+robust to environment quirks). A driver (opencode, or any MCP client) connects and
+gets these tools (opencode shows them prefixed with the server name, e.g.
+`aat_run_tool`):
+
+  capabilities        - list tools/agents/skills; or one capability's full arg schema
+  run_tool            - run a REVERSIBLE tool with structured JSON args
+  run_agent           - run a REVERSIBLE agent
+  run_tool_confirmed  - run a tool INCLUDING irreversible actions (human-approved)
+  run_agent_confirmed - run an agent INCLUDING irreversible actions (human-approved)
+  get_skill           - fetch a skill's markdown (model-decided loading; spec 04)
+
+Two things this fixes vs the B0 bash spike: args are JSON objects (no shell
+quote-escaping) and capability schemas replace `--help` spelunking.
+
+Safety (spec 03): the reversibility gate is CODE, evaluated before execution
+(gate.py -> agents/_lib/reversibility, the same policy as `orchestrator drive` and
+`deputy`). `run_tool`/`run_agent` refuse irreversible actions and return
+`approval_required`, naming the `*_confirmed` path. Only the `*_confirmed` tools are
+marked `ask` in opencode, so a HUMAN approves each side effect; a model cannot forge
+the click and cannot bypass by picking the plain tool. Set AAT_MCP_DENY_IRREVERSIBLE
+for a headless run where even confirmed actions must be refused.
+
+Run:  python webplatform/aat_mcp/server.py         (opencode spawns this over stdio)
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import bridge  # noqa: E402  (sibling module)
+import gate  # noqa: E402
+import protocol  # noqa: E402  (shared MCP mechanics)
+
+SERVER_INFO = {"name": "aat-mcp", "version": "0.2.0"}
+DEFAULT_PROTOCOL = protocol.LEGACY_VERSIONS[0]  # what `initialize` gets when it names no version
+
+_RUN_TOOL_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "tool": {"type": "string", "description": "registered tool name"},
+        "action": {"type": "string", "description": "action name (omit for a flat tool)"},
+        "args": {"type": "object", "description": "flag name -> value (objects/arrays pass cleanly)"},
+    },
+    "required": ["tool"],
+}
+_RUN_AGENT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "agent": {"type": "string", "description": "registered agent name"},
+        "action": {"type": "string", "description": "action name"},
+        "args": {"type": "object", "description": "flag name -> value"},
+    },
+    "required": ["agent"],
+}
+
+TOOLS = [
+    {
+        "name": "capabilities",
+        "description": (
+            "Discover AAT capabilities. No args -> a compact list of every ready "
+            "tool/agent/skill (name, description, primary_action). "
+            "search='<keywords>' -> find the right ACTION by keyword across every "
+            "tool/agent (add name= to search within one). name=<tool or agent> + "
+            "action=<action> -> that one action's full argument schema; use this "
+            "INSTEAD of guessing flags or running --help. name= alone returns the "
+            "whole schema, but for a large tool that is automatically reduced to "
+            "the action-name index - so prefer search= or action=. Optional kind "
+            "filter: tool|agent|skill."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "kind": {"type": "string", "enum": ["tool", "agent", "skill"]},
+                "name": {"type": "string", "description": "tool or agent name"},
+                "action": {"type": "string",
+                           "description": "one action of `name` - returns just its arg schema"},
+                "search": {"type": "string",
+                           "description": "keywords to find a matching action"},
+                "full": {"type": "boolean",
+                         "description": "include the longer description + example per "
+                                        "entry (default false keeps the listing small)"},
+            },
+        },
+    },
+    {
+        "name": "run_tool",
+        "description": (
+            "Run a registered AAT tool for a REVERSIBLE / read action. 'args' is a "
+            "JSON object of flag name->value (objects/arrays pass cleanly, no shell "
+            "escaping). Targets the PROCESIO platform API - see "
+            "https://docs.procesio.com. If the action is irreversible (send/delete/pay/post/...), "
+            "this REFUSES and returns approval_required telling you to use "
+            "run_tool_confirmed. Discover tools/actions via capabilities."
+        ),
+        "inputSchema": _RUN_TOOL_SCHEMA,
+    },
+    {
+        "name": "run_tool_confirmed",
+        "description": (
+            "Run a tool INCLUDING an irreversible action (send/delete/pay/post/"
+            "issue-invoice/...). Targets the PROCESIO platform API - see "
+            "https://docs.procesio.com. The operator is asked to approve before it runs. "
+            "Use this only after run_tool returned approval_required, or when you "
+            "know the action has a real-world side effect."
+        ),
+        "inputSchema": _RUN_TOOL_SCHEMA,
+    },
+    {
+        "name": "run_agent",
+        "description": (
+            "Run a registered AAT agent for a REVERSIBLE action. In an interactive "
+            "session, route a substantive request first with agent='orchestrator', "
+            "action='intake', args={'request': '<the ask>'} (per AGENTS.md). If you "
+            "were told you are already inside one step of an externally-managed plan, "
+            "do NOT route or plan - act directly; 'orchestrator drive' is refused "
+            "there because it would start a second orchestration loop. Irreversible "
+            "agent actions are refused here - use run_agent_confirmed."
+        ),
+        "inputSchema": _RUN_AGENT_SCHEMA,
+    },
+    {
+        "name": "run_agent_confirmed",
+        "description": (
+            "Run an agent INCLUDING an irreversible action. The operator is asked to "
+            "approve before it runs."
+        ),
+        "inputSchema": _RUN_AGENT_SCHEMA,
+    },
+    {
+        "name": "get_skill",
+        "description": (
+            "Fetch a registered skill's SKILL.md plus a metadata-only resource index. "
+            "To retrieve one bundled resource, pass a path from that index in the "
+            "optional resource field."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "resource": {"type": "string"},
+            },
+            "required": ["name"],
+        },
+    },
+]
+
+
+# Titles and hints, kept in one table so the claim each tool makes about itself can be
+# audited in one place. The hints drive auto-permissions in a client: a readOnlyHint tool
+# may run without asking, so a wrong one here is a write that fires unprompted.
+#
+# run_* are NOT read-only. They dispatch any registered action, and the reversible set
+# they admit still includes creates and updates (add-credential, datastore-add-rows,
+# update-*). "Reversible" answers whether a thing can be undone; "read-only" answers
+# whether it changes anything, and those are different questions. Mapping one onto the
+# other would mislabel roughly ninety write actions as safe to run unattended.
+_ANNOTATIONS = {
+    "capabilities":        ("Discover PROCESIO capabilities", True),
+    "get_skill":           ("Read a PROCESIO skill", True),
+    "run_tool":            ("Run a PROCESIO tool action", False),
+    "run_tool_confirmed":  ("Run a PROCESIO tool action (approval required)", False),
+    "run_agent":           ("Run a PROCESIO agent action", False),
+    "run_agent_confirmed": ("Run a PROCESIO agent action (approval required)", False),
+}
+
+for _t in TOOLS:
+    _title, _read_only = _ANNOTATIONS[_t["name"]]
+    _t["title"] = _title
+    _t["annotations"] = {
+        "title": _title,
+        "readOnlyHint": _read_only,
+        # A dispatcher can reach an update, which overwrites data. Only a tool that
+        # cannot change anything may claim otherwise.
+        "destructiveHint": not _read_only,
+        "idempotentHint": _read_only,
+        # Read-only calls answer from the local registry; the rest reach the platform.
+        "openWorldHint": not _read_only,
+    }
+
+
+def _log(msg: str) -> None:
+    print(f"[aat-mcp] {msg}", file=sys.stderr, flush=True)
+
+
+def _run(kind: str, arguments: dict, confirmed: bool) -> tuple[dict, bool]:
+    """Execute a tool/agent through the reversibility gate.
+
+    kind: 'tool' or 'agent'. confirmed: True for the *_confirmed tools (opencode has
+    already asked the operator). Returns (payload, is_error)."""
+    key = "tool" if kind == "tool" else "agent"
+    target = arguments.get(key)
+    if not target:
+        return {"error": f"run_{kind} requires '{key}'"}, True
+    action = arguments.get("action")
+    verdict = gate.classify(target, action)
+
+    if not confirmed and not verdict["reversible"]:
+        # Plain tool refuses an irreversible action and names the confirmed path.
+        return {"approval_required": {
+            key: target, "action": action, "verb": verdict["verb"],
+            "blast_class": verdict["blast_class"], "reason": verdict["reason"],
+            "next": (f"This action is irreversible ({verdict['blast_class']}). To "
+                     f"proceed, call run_{kind}_confirmed with the same arguments - "
+                     f"the operator will be asked to approve it."),
+        }}, False
+
+    if confirmed and not verdict["reversible"] and gate.deny_irreversible_env():
+        # Headless fail-safe: no human in the seat to approve.
+        return {"refused": ("irreversible action denied (AAT_MCP_DENY_IRREVERSIBLE "
+                            "is set; no human in the seat)"),
+                "verb": verdict["verb"], "blast_class": verdict["blast_class"]}, True
+
+    runner = bridge.run_tool if kind == "tool" else bridge.run_agent
+    res = runner(target, action, arguments.get("args"))
+    if not res.get("ok", False):
+        # Recovery hint so the driver re-discovers instead of guessing again, falling
+        # back to bash, or claiming it lacks access (observed with weaker models on a
+        # bad action/args or a transient tool error).
+        res = dict(res)
+        res["hint"] = (f"This {kind} call failed - it does NOT mean you lack access. "
+                       f"Call capabilities with name='{target}' and action='{action}' "
+                       f"(or search='<keywords>') to see the valid args, then retry "
+                       f"run_{kind}. Do NOT fall back to bash.")
+        schema = _usage_help(kind, target, action, res)
+        if schema:
+            res["schema"] = schema
+        return res, True
+    return res, False
+
+
+# A usage failure is a naming failure: a flag spelled `workspace_id` instead of
+# `workspace-id`, an invented action, or a required arg the caller probed for by
+# calling the action empty. The framework already knows the right answer at this
+# exact moment - it just never said it, so the model guessed again (measured: the
+# same action retried with four different arg spellings). Answering here fixes it
+# for every tool at once, with no per-tool change.
+_USAGE_MARKERS = ("unknown action", "unrecognized arguments",
+                  "arguments are required", "invalid choice")
+
+
+def _usage_help(kind: str, target: str, action: str | None, res: dict) -> dict | None:
+    """Attach the valid action/arg names when a call failed on USAGE, not on the
+    remote system. Never raises - enrichment must not turn into a second error."""
+    err = res.get("error") or {}
+    message = str(err.get("message") or "")
+    if not any(marker in message for marker in _USAGE_MARKERS):
+        return None
+    try:
+        return bridge.action_help(target, action, kind)
+    except Exception:  # noqa: BLE001 - best effort; the original error still stands
+        return None
+
+
+def _call_tool(name: str, arguments: dict) -> tuple[dict, bool]:
+    """Return (result_payload, is_error). Never raises: failures come back as a
+    structured payload the model can read."""
+    try:
+        if name == "capabilities":
+            return bridge.capabilities(arguments.get("kind"), arguments.get("name"),
+                                       arguments.get("action"),
+                                       arguments.get("search"),
+                                       bool(arguments.get("full", False))), False
+        if name == "run_tool":
+            return _run("tool", arguments, confirmed=False)
+        if name == "run_tool_confirmed":
+            return _run("tool", arguments, confirmed=True)
+        if name == "run_agent":
+            return _run("agent", arguments, confirmed=False)
+        if name == "run_agent_confirmed":
+            return _run("agent", arguments, confirmed=True)
+        if name == "get_skill":
+            if not arguments.get("name"):
+                return {"error": "get_skill requires 'name'"}, True
+            if "resource" in arguments:
+                return bridge.get_skill_resource(arguments["name"], arguments["resource"]), False
+            return bridge.get_skill(arguments["name"]), False
+        return {"error": f"unknown tool: {name}"}, True
+    except KeyError as e:
+        return {"error": str(e)}, True
+    except Exception as e:  # noqa: BLE001 - surface as a readable tool error
+        return {"error": f"{type(e).__name__}: {e}"}, True
+
+
+def handle(req: dict, *, modern: bool = True) -> dict | None:
+    """Dispatch one JSON-RPC request. Returns a response dict, or None for a
+    notification (no response).
+
+    The protocol mechanics - version negotiation and the 2026-07-28 era - live in
+    protocol.py, shared with the chat surface; this server supplies only its tools and its
+    dispatcher. ``modern=False`` is for the HTTP transport, which serves the legacy era only."""
+    return protocol.handle(req, tools=TOOLS, call_tool=_call_tool,
+                           server_info=SERVER_INFO, modern=modern)
+
+
+def main() -> None:
+    _log("started (stdio). Waiting for JSON-RPC on stdin.")
+    protocol.serve_stdio(handle, _log)
+
+
+if __name__ == "__main__":
+    main()

procesio_cli/webplatform/aat_mcp/tests/conftest.py

@@ -0,0 +1,8 @@
+import sys
+from pathlib import Path
+
+# Make the aat_mcp package modules (bridge, server) importable under pytest's
+# importlib mode without turning aat_mcp into an installed package.
+_AAT_MCP = Path(__file__).resolve().parents[1]
+if str(_AAT_MCP) not in sys.path:
+    sys.path.insert(0, str(_AAT_MCP))