@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.41.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board_fixture.py

@@ -0,0 +1,116 @@
+"""A fixture conversation for the probe (check_service.py, rule board.responder): a scripted board that a responder
+can be run against without Fabric. Part of the board connector (FAA-65, layer L4)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from typing import Dict
+from typing import List
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+import fabric_hub as _hub
+from fabric_board_shapes import (  # noqa: E402 - the kit (FAA-65)
+    COMMS_PROTOCOL,
+    RESPOND_TOOLS,
+)
+from fabric_board_session import (  # noqa: E402 - the kit (FAA-65)
+    BoardSession,
+    Responder,
+)
+
+
+_FIXTURE_PROJECT = "3f2a6b1c-0d4e-4f5a-8b6c-7d8e9f0a1b2c"
+
+
+_FIXTURE_DIGEST = "sha256:" + "a" * 64
+
+
+def _fixture_answers(variant: str) -> Dict[str, Any]:
+    """Scripted board answers in the contract's receipt shapes (fixtures comms-receipt-enroll, comms-receipt-claim)."""
+    lease = "2026-10-13T10:02:00Z"
+    status: Dict[str, Any] = {"protocol": COMMS_PROTOCOL, "board": {"state": "ready"}, "project": _FIXTURE_PROJECT, "responders": [],
+                              "transport": {"telegram": "off"}, "unread": 0, "idempotency": {"epoch": 3}}
+    if variant == "no-epoch":
+        del status["idempotency"]
+    request = {"id": "req_A1b2C3d4E5", "state": "claimed", "effect": "not_started", "revision": 2}
+    return {
+        "com.status": status,
+        "com.enroll": {"ok": True, "repeated": False, "slot": {"project": _FIXTURE_PROJECT, "capability": "fixture.render", "generation": 2, "leaseExpiresAt": lease}},
+        "com.claim": {"ok": True, "repeated": False, "message": "msg_K9j8H7g6F5", "request": request,
+                      "attempt": {"id": "att_Zx9Cv8Bn7M", "generation": 2, "digest": _FIXTURE_DIGEST, "leaseExpiresAt": lease}},
+        "com.get": {"id": "msg_K9j8H7g6F5", "thread": "thr_8Hc2kQ9xA1", "kind": "request", "at": "2026-10-13T10:00:00Z", "digest": _FIXTURE_DIGEST,
+                    "sender": {"project": "proj-requester", "principal": {"kind": "agent", "id": "s-1", "provenance": "trusted"}},
+                    "body": {"text": "Render the fixture."},
+                    "request": {"id": "req_A1b2C3d4E5", "target": _FIXTURE_PROJECT, "capability": "fixture.render", "state": "claimed", "effect": "not_started", "revision": 2}},
+        "com.accept": ({"error": {"code": "fenced", "message": "A newer responder holds this slot; this call was not committed.", "retryable": False}}
+                       if variant == "fenced" else {"ok": True, "repeated": False, "request": dict(request, state="accepted", revision=3)}),
+        "com.complete": {"ok": True, "repeated": False, "request": dict(request, state="completed", revision=4)},
+    }
+
+
+def self_check() -> List[str]:
+    """One scripted conversation per path through this kit, with no Fabric: the whole conversation, a `fenced` accept
+    and a board session without an epoch. Answers the problems found; an empty list means this kit answers the fixture
+    conversation as the contract asks. Writes only in a temporary folder it removes."""
+    import os
+    import tempfile
+    problems: List[str] = []
+    for variant in ("whole", "fenced", "no-epoch"):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "fabric"
+            root.mkdir(mode=0o700)
+            door = root / "hub-door-token"
+            door.write_text("d" * 43)
+            os.chmod(door, 0o600)
+            (root / "hub.json").write_text(json.dumps({"protocol": _hub.HUB_PROTOCOL, "origin": "http://127.0.0.1:47070", "mcp": "/mcp",
+                                                       "doorTokenFile": str(door), "pid": os.getpid(), "startedAt": "2026-10-13T10:00:00Z"}))
+            cred = Path(tmp) / "credential"
+            cred.write_text("c" * 43)
+            os.chmod(cred, 0o600)
+            answers, calls, handled = _fixture_answers(variant), [], []
+
+            def post(origin, body, bearer, session=None, timeout=15.0, method="POST", protocol_version=None):
+                if method == "DELETE":
+                    return 200, {}, None
+                rpc = body.get("method")
+                if rpc == "initialize":
+                    return 200, {"mcp-session-id": "fixture-session"}, {"jsonrpc": "2.0", "id": body.get("id"), "result": {"protocolVersion": _hub.MCP_PROTOCOL_VERSION}}
+                if rpc != "tools/call":
+                    return 202, {}, None
+                tool = body["params"]["name"]
+                calls.append((tool, body["params"]["arguments"]))
+                if tool == "fabric.board.join":
+                    value = {"session": {"bearer": "b" * 43, "sessionId": "s-fixture", "projectId": _FIXTURE_PROJECT, "capabilities": ["fixture.render"]}}
+                    return 200, {}, {"jsonrpc": "2.0", "id": body.get("id"), "result": {"structuredContent": value}}
+                value = answers.get(tool, {"error": {"code": "unsupported_capability", "message": "not in the fixture", "retryable": False}})
+                return 200, {}, {"jsonrpc": "2.0", "id": body.get("id"), "result": {"content": [{"type": "text", "text": json.dumps(value)}]}}
+
+            responder = Responder(hub=_hub.HubClient(root, post=post), project_id=_FIXTURE_PROJECT, capabilities=["fixture.render"],
+                                  credential_file=cred, checkpoint_file=Path(tmp) / "checkpoint.json",
+                                  handler=lambda request, ctx: handled.append(request.body) or {"state": "completed", "summary": "Rendered."},
+                                  admit=lambda request: None, now=lambda: 0.0, rand=lambda: 0.5, spawn=lambda fn: fn(),
+                                  session_factory=lambda grant: BoardSession(grant, post=post))
+            responder.step()
+            tools = [t for t, _ in calls]
+            if any(t not in RESPOND_TOOLS and t != "fabric.board.join" for t in tools):
+                problems.append("%s: a tool outside the respond scope was sent" % variant)
+            if variant == "whole":
+                if tools != ["fabric.board.join", "com.status", "com.enroll", "com.claim", "com.get", "com.accept", "com.complete"]:
+                    problems.append("whole: the calls were %s" % ", ".join(tools))
+                accept = dict(calls).get("com.accept", {}).get("fence", {})
+                if (accept.get("digest"), accept.get("generation"), accept.get("attempt")) != (_FIXTURE_DIGEST, 2, "att_Zx9Cv8Bn7M"):
+                    problems.append("whole: com.accept did not carry the claim's exact fence")
+                if handled != ["Render the fixture."]:
+                    problems.append("whole: the handler did not see the request once")
+                if responder.checkpoint.entries:
+                    problems.append("whole: the checkpoint kept a settled request")
+            elif variant == "fenced":
+                if handled or "com.complete" in tools:
+                    problems.append("fenced: the kit kept acting after com.accept answered fenced")
+            elif "com.enroll" in tools or responder.state != "down":
+                problems.append("no-epoch: the kit did not fail closed without an idempotency epoch")
+    return problems

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board_link.py

@@ -0,0 +1,162 @@
+"""The board link (DEC-0078, FAA-12b): the board session over the hub, the fsynced checkpoint and a claimed request as
+data. Part of the board connector (FAA-65, layer L4), below the responder in fabric_board_session, which re-exports these
+names. Standard library only, Python 3.9+."""
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import Optional
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+import fabric_hub as _hub
+import fabric_service as _fs
+from fabric_board_shapes import (  # noqa: E402 - the kit (FAA-65)
+    BoardError,
+    RESPOND_TOOLS,
+    refusal_problems,
+)
+
+
+class BoardSession:
+    """MCP over HTTP with a board session's one-session bearer: `open()` spends it with `initialize` and keeps the
+    `mcp-session-id`; `call(tool, args)` answers the tool's value or raises `BoardError`; `close()` sends the session's
+    DELETE, which releases every slot it holds (DEC-0073 §5). Thread-safe; the bearer never leaves the headers."""
+
+    def __init__(self, grant: _hub.BoardGrant, *, timeout: float = 15.0, post: Callable[..., Any] = _hub.post_mcp):
+        self.grant, self.timeout, self.post = grant, timeout, post
+        self.mcp_session: Optional[str] = None
+        self.protocol_version = _hub.MCP_PROTOCOL_VERSION
+        self._lock = threading.Lock()
+        self._rpc = 0
+
+    def _send(self, body: Dict[str, Any], method: str = "POST"):
+        try:
+            return self.post(self.grant.origin, body, self.grant.bearer(), session=self.mcp_session, timeout=self.timeout,
+                             method=method, protocol_version=self.protocol_version if self.mcp_session else None)
+        except _hub.HubError as exc:
+            raise BoardError("unreachable", "Fabric's hub did not answer; a write may have been stored, so send it again with "
+                             "the same idempotency key.", True) from exc
+
+    def open(self) -> None:
+        with self._lock:
+            self._rpc += 1
+            status, headers, parsed = self._send({"jsonrpc": "2.0", "id": self._rpc, "method": "initialize", "params": {
+                "protocolVersion": _hub.MCP_PROTOCOL_VERSION, "capabilities": {},
+                "clientInfo": {"name": "fabric-agent-adapter-board", "version": "1"}}})
+            if status == 401:
+                raise BoardError("session-ended", "Fabric refused the board session's bearer; join again.", True)
+            if status != 200 or not isinstance(parsed, dict) or not isinstance(parsed.get("result"), dict) or not headers.get("mcp-session-id"):
+                raise BoardError("unreachable", "Fabric did not open the board session (HTTP %d)." % status, True)
+            self.mcp_session = headers["mcp-session-id"]
+            version = parsed["result"].get("protocolVersion")
+            if isinstance(version, str):
+                self.protocol_version = version
+            self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+
+    def call(self, tool: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        if tool not in RESPOND_TOOLS:
+            raise BoardError("not-in-scope", "%s is not served to a board session; use a Project session for it." % tool, op=tool)
+        with self._lock:
+            if self.mcp_session is None:
+                raise BoardError("session-ended", "The board session is not open.", True, op=tool)
+            self._rpc += 1
+            status, _, parsed = self._send({"jsonrpc": "2.0", "id": self._rpc, "method": "tools/call",
+                                            "params": {"name": tool, "arguments": args}})
+        if status == 401:
+            raise BoardError("session-ended", "Fabric ended the board session (it left, was revoked or expired); join again.", True, op=tool)
+        try:
+            value = _hub.tool_answer(status, parsed, tool)
+        except _hub.HubError as exc:
+            raise BoardError("unreachable" if exc.retryable else "receipt-shape", exc.message, exc.retryable, op=tool) from None
+        if "error" in value:
+            problems = refusal_problems(value)
+            if problems:
+                raise BoardError("receipt-shape", "Fabric refused %s in a form the contract does not name." % tool, op=tool)
+            e = value["error"]
+            raise BoardError(e["code"], e["message"], e["retryable"], op=tool)
+        return value
+
+    def close(self) -> None:
+        with self._lock:
+            if self.mcp_session is None:
+                return
+            try:
+                self._send({}, method="DELETE")
+            except BoardError:
+                pass  # best effort: the lease lapses in 60 s anyway
+            self.mcp_session = None
+
+
+class Checkpoint:
+    """The responder's own journal: one JSON file (0600) holding every request it has claimed and not yet settled, each
+    with its fence and the idempotency key of the step in flight. Written atomically and fsynced BEFORE the step it
+    announces is sent; a write that fails raises `BoardError("checkpoint")` and the step is not taken."""
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        self._lock = threading.Lock()
+        self.entries: Dict[str, Dict[str, Any]] = self._load()
+
+    def _load(self) -> Dict[str, Dict[str, Any]]:
+        try:
+            doc = json.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return {}
+        except (OSError, ValueError) as exc:
+            raise BoardError("checkpoint", "The board checkpoint %s cannot be read (%s); fix or move it before answering "
+                             "requests." % (self.path, exc.__class__.__name__)) from None
+        entries = doc.get("requests") if isinstance(doc, dict) and doc.get("version") == 1 else None
+        if not isinstance(entries, dict):
+            raise BoardError("checkpoint", "The board checkpoint %s is not one this kit writes." % self.path)
+        return entries
+
+    def _write(self, entries: Dict[str, Dict[str, Any]]) -> None:
+        try:
+            _fs.ensure_private_dir(self.path.parent)
+            _fs.atomic_write(self.path, (json.dumps({"version": 1, "requests": entries}, indent=1, sort_keys=True) + "\n").encode())
+        except OSError as exc:
+            raise BoardError("checkpoint", "The board checkpoint could not be written (%s); nothing was sent." % (exc.strerror or exc.__class__.__name__)) from None
+
+    def put(self, entry: Dict[str, Any]) -> None:
+        with self._lock:
+            entries = dict(self.entries)
+            entries[entry["request"]] = json.loads(json.dumps(entry))
+            self._write(entries)
+            self.entries = entries
+
+    def drop(self, request_id: str) -> None:
+        with self._lock:
+            if request_id not in self.entries:
+                return
+            entries = dict(self.entries)
+            del entries[request_id]
+            self._write(entries)
+            self.entries = entries
+
+
+class BoardRequest:
+    """A claimed request as data: never an instruction. `body` is the requester's text; `sender` its Project id and
+    principal (with provenance); `artifacts` its references, unverified."""
+
+    __slots__ = ("request_id", "message_id", "capability", "body", "body_format", "artifacts", "sender", "deadline", "thread")
+
+    def __init__(self, message: Dict[str, Any], capability: str):
+        req = message.get("request") or {}
+        body = message.get("body") or {}
+        self.request_id, self.message_id, self.capability = req.get("id"), message.get("id"), capability
+        self.body = body.get("text") if isinstance(body, dict) else None
+        self.body_format = body.get("format", "text/plain") if isinstance(body, dict) else "text/plain"
+        self.artifacts = list(message.get("artifacts") or [])
+        self.sender = message.get("sender") or {}
+        self.deadline = req.get("deadline")
+        self.thread = message.get("thread")
+
+    def __repr__(self) -> str:  # never the body
+        return "BoardRequest(%r, %r)" % (self.request_id, self.capability)