@passioncode-ai/fabric-agent-adapter 0.4.2 → 0.5.0

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/fabric_provider.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Write and remove fabric-provider/0.1 entries: agents that are not services.
+
+An agent reached as a CLI or a stdio MCP server announces itself with one entry in
+the providers directory, beside the services directory. Only its installer writes the
+entry and only its uninstaller removes it; the entry grants no Project access.
+Standard library only; it does not import the service kit, so this skill stands alone.
+
+  fabric_provider.py write --id ID --name NAME --manifest PATH --installed-by TEXT
+                           (--url http://127.0.0.1:PORT/mcp | --stdio EXECUTABLE [ARG ...])
+                           [--env NAME=secret-ref:REF ...] [--summary TEXT] [--repository URL]
+  fabric_provider.py remove ID
+  fabric_provider.py validate PATH
+
+Normative source: fabric-agent-contract docs/specification/provider.md (DEC-0016).
+"""
+
+# #region provider-writer — docs: plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-entry.md#the-writer
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+from typing import Any, Dict, List, Optional
+
+PROTOCOL = "fabric-provider/0.1"
+_ID = re.compile(r"^[a-z][a-z0-9-]{1,62}$")
+_ENV_NAME = re.compile(r"^[A-Z_][A-Z0-9_]*$")
+_SECRET_REF = re.compile(r"^secret-ref:([A-Za-z0-9][A-Za-z0-9._/:@-]{0,255})$")
+_LOCAL_PATH = re.compile(r"^(~/|/)[^\x00]*$")
+_URL = re.compile(r"^http://127\.0\.0\.1:([0-9]{1,5})/mcp$")
+FIELDS = {"protocol", "id", "name", "summary", "manifest", "run", "source", "installedAt", "installedBy", "extensions"}
+# FAC-SEM-015 reads a credential by its SHAPE: a reference named after a key is fine.
+CREDENTIAL_SHAPES = [re.compile(p) for p in (
+    r"^(sk|pk|rk)[-_](live|test|proj|or|ant)?[-_]?[A-Za-z0-9_-]{16,}",
+    r"^(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}",
+    r"^github_pat_[A-Za-z0-9_]{20,}",
+    r"^xox[abprs]-[A-Za-z0-9-]{10,}",
+    r"^(AKIA|ASIA)[A-Z0-9]{16}$",
+    r"^lin_api_[A-Za-z0-9]{20,}",
+    r"^AIza[0-9A-Za-z_-]{30,}",
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
+    r"^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$",
+    r"^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])[A-Za-z0-9+=_-]{32,}$",
+)]
+
+
+class ProviderError(Exception):
+    """An entry was refused; the message is one readable sentence and never quotes a value."""
+
+
+def services_dir() -> Path:
+    override = os.environ.get("FABRIC_SERVICES_DIR")
+    if override:
+        return Path(override).expanduser()
+    home = Path.home()
+    if sys.platform == "darwin":
+        return home / "Library/Application Support/ai.passioncode.fabric/services"
+    return Path(os.environ.get("XDG_DATA_HOME") or str(home / ".local/share")) / "passioncode-fabric/services"
+
+
+def providers_dir() -> Path:
+    """FABRIC_PROVIDERS_DIR, else `providers/` in the same root as `services/`."""
+    override = os.environ.get("FABRIC_PROVIDERS_DIR")
+    if override:
+        return Path(override).expanduser()
+    return services_dir().parent / "providers"
+
+
+def looks_like_credential(value: str) -> bool:
+    return any(shape.search(value) for shape in CREDENTIAL_SHAPES)
+
+
+def validate_provider_entry(entry: Any) -> List[str]:
+    """Mirrors provider.schema.json and FAC-SEM-015 (the schema stays normative)."""
+    if not isinstance(entry, dict):
+        return ["an entry is a JSON object"]
+    problems: List[str] = []
+    for key in ("protocol", "id", "name", "manifest", "run", "installedAt", "installedBy"):
+        if key not in entry:
+            problems.append("missing %s" % key)
+    for key in sorted(set(entry) - FIELDS):
+        problems.append("unknown field %s" % key)
+    if problems:
+        return problems
+    if entry["protocol"] != PROTOCOL:
+        problems.append("protocol must be %s" % PROTOCOL)
+    if not _ID.match(str(entry["id"])):
+        problems.append("id must match %s" % _ID.pattern)
+    if not isinstance(entry["name"], str) or not 1 <= len(entry["name"]) <= 80:
+        problems.append("name is 1 to 80 characters")
+    if "summary" in entry and (not isinstance(entry["summary"], str) or len(entry["summary"]) > 200):
+        problems.append("summary is at most 200 characters")
+    manifest = str(entry["manifest"])
+    if not _LOCAL_PATH.match(manifest) or not re.search(r"(^|/)fabric-agent\.json$", manifest):
+        problems.append("manifest is an absolute or ~/ path to fabric-agent.json")
+    problems.extend(_run_problems(entry["run"]))
+    return problems
+
+
+def _run_problems(run: Any) -> List[str]:
+    mcp = run.get("mcp") if isinstance(run, dict) and set(run) == {"mcp"} else None
+    if not isinstance(mcp, dict) or len(mcp) != 1 or not set(mcp) <= {"stdio", "url"}:
+        return ["run is {mcp: {stdio: ...}} or {mcp: {url: ...}}, exactly one"]
+    if "url" in mcp:
+        match = _URL.match(str(mcp["url"]))
+        return [] if match and 1 <= int(match.group(1)) <= 65535 else ["run.mcp.url is http://127.0.0.1:<port>/mcp"]
+    stdio = mcp["stdio"]
+    problems: List[str] = []
+    if not isinstance(stdio, dict) or not set(stdio) <= {"command", "env"} or "command" not in stdio:
+        return ["run.mcp.stdio is {command, env?}"]
+    command = stdio["command"]
+    if not isinstance(command, list) or not 1 <= len(command) <= 32 or not all(isinstance(a, str) and a for a in command):
+        problems.append("run.mcp.stdio.command is an argument array, never a shell string")
+    env = stdio.get("env", {})
+    if not isinstance(env, dict):
+        return problems + ["run.mcp.stdio.env is an object"]
+    for name, value in env.items():
+        if not _ENV_NAME.match(name):
+            problems.append("env name %s is not an environment variable name" % name)
+        reference = _SECRET_REF.match(value) if isinstance(value, str) else None
+        if not reference or looks_like_credential(reference.group(1)):
+            problems.append("env %s must be a secret reference (secret-ref:<name>), never a secret value (FAC-SEM-015)" % name)
+    return problems
+
+
+def _atomic_write(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+    fd, tmp = tempfile.mkstemp(prefix="." + path.name + ".", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _service_ids(directory: Path) -> Dict[str, str]:
+    ids: Dict[str, str] = {}
+    if directory.is_dir():
+        for path in sorted(directory.glob("*.json")):
+            try:
+                ids.setdefault(str(json.loads(path.read_text(encoding="utf-8")).get("id")), path.name)
+            except (OSError, ValueError, AttributeError):
+                continue
+    return ids
+
+
+def write_provider_entry(entry: Dict[str, Any], directory: Optional[Path] = None, services: Optional[Path] = None) -> Path:
+    """Installer-only. Refuses an invalid entry and an id that is already a service (FAC-SEM-013)."""
+    problems = validate_provider_entry(entry)
+    if problems:
+        raise ProviderError("Provider entry is invalid: %s." % "; ".join(problems))
+    clash = _service_ids(services or services_dir()).get(entry["id"])
+    if clash:
+        raise ProviderError("%s is already a service (%s); an id is a service or a provider, never both (FAC-SEM-013)." % (entry["id"], clash))
+    target = (directory or providers_dir()) / ("%s.json" % entry["id"])
+    _atomic_write(target, (json.dumps(entry, indent=2, ensure_ascii=False) + "\n").encode())
+    return target
+
+
+def remove_provider_entry(provider_id: str, directory: Optional[Path] = None) -> bool:
+    """Uninstaller-only. Returns whether there was an entry to remove."""
+    if not _ID.match(provider_id):
+        raise ProviderError("Provider id %s does not match %s." % (provider_id, _ID.pattern))
+    try:
+        ((directory or providers_dir()) / ("%s.json" % provider_id)).unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _now() -> str:
+    return dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    write = sub.add_parser("write")
+    write.add_argument("--id", required=True)
+    write.add_argument("--name", required=True)
+    write.add_argument("--summary")
+    write.add_argument("--manifest", required=True)
+    write.add_argument("--installed-by", required=True)
+    write.add_argument("--repository")
+    write.add_argument("--env", action="append", default=[], help="NAME=secret-ref:REF (a reference, never a value)")
+    transport = write.add_mutually_exclusive_group(required=True)
+    transport.add_argument("--url")
+    transport.add_argument("--stdio", nargs=argparse.REMAINDER, help="the executable and its arguments, last on the line")
+    remove = sub.add_parser("remove")
+    remove.add_argument("id")
+    check = sub.add_parser("validate")
+    check.add_argument("path", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "remove":
+            print("removed" if remove_provider_entry(args.id) else "no entry for %s" % args.id)
+            return 0
+        if args.command == "validate":
+            problems = validate_provider_entry(json.loads(args.path.read_text(encoding="utf-8")))
+            print("; ".join(problems) if problems else "valid")
+            return 1 if problems else 0
+        env: Dict[str, str] = {}
+        for pair in args.env:
+            name, sep, value = pair.partition("=")
+            if not sep:
+                raise ProviderError("--env takes NAME=secret-ref:REF.")
+            env[name] = value
+        run: Dict[str, Any] = {"mcp": {"url": args.url}} if args.url else {"mcp": {"stdio": {"command": args.stdio}}}
+        if env and args.stdio:
+            run["mcp"]["stdio"]["env"] = env
+        entry: Dict[str, Any] = {"protocol": PROTOCOL, "id": args.id, "name": args.name, "manifest": args.manifest,
+                                 "run": run, "installedAt": _now(), "installedBy": args.installed_by}
+        if args.summary:
+            entry["summary"] = args.summary
+        if args.repository:
+            entry["source"] = {"repository": args.repository}
+        print(write_provider_entry(entry))
+        return 0
+    except (ProviderError, OSError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+# #endregion provider-writer

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: building-fabric-services
 description: >-
-  Use when building or running an agent as a long-lived local service with a dashboard on the
-  operator's Mac — «сделай агенту дашборд», «локальный сервис агента», «дашборд должен всегда
+  Use when building or running an agent as a long-lived local service with a dashboard on
+  a macOS machine — «сделай агенту дашборд», «локальный сервис агента», «дашборд должен всегда
   работать и не плодить копии», «где агенту хранить настройки», «подключи агента к Fabric
   Dashboards», "make this agent a local service", "always-on dashboard", "fabric-service
   protocol", "add the well-known endpoint", "migrate a service to fabric-service". Covers the
@@ -11,14 +11,14 @@ description: >-
   descriptor, the well-known document, the events feed and notifications; ships Python and Node
   reference kits and a live conformance probe. NOT for a one-off script or cron job, a hosted
   SaaS, the provider manifest itself (adapting-projects-to-fabric), or building Fabric Dashboards.
-license: MIT
+license: PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only (Linux services use lifecycle manager none until a systemd adapter exists). No network or package install; the contract checkout is optional.
 metadata:
-  author: passioncode-ai
-  version: "0.4.2"
+  author: PassionCode.ai
+  version: "0.5.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "a5a27092ba0dcc5facfbeae8b359146dfb403e9a"
+  extension-commit: "a22dea359ba04b8fe549abe81a5131552cb90eff"
 ---
 
 # Building Fabric services
@@ -73,6 +73,13 @@ Answer before writing code, and record the answers in the project README:
 Read [the surfaces and auth reference](references/surfaces-and-auth.md) when wiring
 MCP registration into a client config, the login flow or the CSRF header.
 
+When other agents or Fabric call the service over MCP, it follows `fabric-interop/0.1`:
+each manifest capability is the tool of its name, long work is a job with a stable id,
+a question for a person is an elicitation, and every call carries one trace. Read
+[the interop reference](references/interop.md) before writing an MCP tool; the helpers
+are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
+[`scripts/fabric-interop.mjs`](scripts/fabric-interop.mjs).
+
 ## Step 2 — the non-negotiables
 
 1. **Loopback only.** Bind `127.0.0.1`. Refuse any `Host` other than
@@ -144,6 +151,13 @@ On every request call `check_request(port, host, origin, sec_fetch_site)` and an
 `SIGTERM` drains in-flight work within `ExitTimeOut`, then exits; interrupted work
 resumes on the next start.
 
+The MCP surface (`POST /mcp`, service token) is `fabric_interop.McpToolServer.handle`
+in Python; jobs live in `fabric_interop.JobStore(dirs["data"] / "jobs")`, created after
+the lock like every other piece of state. Add `"mcp": {"path": "/mcp", "transport":
+"streamable-http", "capabilities": [...]}` to the well-known surfaces, and point the
+descriptor's `fabricManifest` at a manifest whose service key names this
+`<id>.<instance>` — `sample_service.py register` shows both.
+
 ## Step 4 — install it
 
 The installer, not the service, owns the plist and the descriptor. Sequence:
@@ -186,7 +200,9 @@ python3 <skill-dir>/scripts/check_service.py <id>[.<instance>]
 It reports `PASS`, `FAIL` or `NOT_RUN` per rule (descriptor, port claim, well-known
 shape, identity, latency, Host/Origin/cross-site guards, loopback bind, token file,
 events auth and shape, single-use login, state outside code, instance lock, plist,
-launchd pid equals answering pid) and exits 1 on any `FAIL`. A `NOT_RUN` is not a pass —
+launchd pid equals answering pid, and the `interop.*` rules: manifest link, capability
+list, tools equal to the manifest, job tools, unknown job, trace propagation, event
+trace pairs) and exits 1 on any `FAIL`. A `NOT_RUN` is not a pass —
 name it in the report.
 
 Then prove the lock: start a second copy by hand against the same data directory; it

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/interop.md

@@ -0,0 +1,77 @@
+# Being called: `fabric-interop/0.1`
+
+Normative source: the Fabric Agent Contract's `docs/specification/interop.md` (DEC-0016)
+at the commit this plugin pins. This page says how the kit implements it; where the two
+differ, the contract is right.
+
+A service that other agents — and Fabric — call does five things. Each has one helper in
+`scripts/fabric_interop.py` (Python) and `scripts/fabric-interop.mjs` (Node).
+
+| Rule | What the service does | Helper |
+|---|---|---|
+| C3.1 capability = tool | serves each `mcp` capability of its manifest as the MCP tool of the same name, with the manifest's two schemas unchanged and annotations from the effect | `tool_for_capability` / `toolForCapability`, `expected_annotations` |
+| C3.2 long work = job | a capability whose work can outlive one request declares `"job": true` in its interop block, returns `{"job": {"id", "status": "working"}}`, and serves `fabric.job.get` and `fabric.job.cancel` | `JobStore`, `McpToolServer` (Python), `unknown_job_result` |
+| C3.2 result | a completed job carries the result envelope: `done`, `proof`, `scope`, `notVerified`, `output`, `usage` | `result_envelope` / `resultEnvelope` |
+| C3.3 a person decides | the job goes `input_required` with an elicitation: a titled single-select in form mode, and URL mode for anything secret | `choice_request`, `form_request`, `url_request` |
+| C3.4 trace | every call runs as a child span of the caller's `_meta.traceparent`; outgoing calls carry the same trace; events about the work carry `traceId` and `spanId` | `child_traceparent`, `trace_ids`, `make_event(..., trace_id=, span_id=)` |
+
+The interop block sits in the manifest under the capability's `extensions`:
+
+```json
+"extensions": { "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1": { "job": true } }
+```
+
+That key has one spelling (the contract's `src/extensions.ts`); copy it, never retype it.
+
+## The kit
+
+```python
+import fabric_interop as fi
+
+jobs = fi.JobStore(data_dir / "jobs")               # one private JSON file per job; ids survive restarts
+server = fi.McpToolServer("example-agent", "1.0.0", jobs=jobs,
+                          on_job_started=start_report, on_input=resume_report)
+server.add_tool(fi.tool_for_capability(capability, input_schema, output_schema), handler)
+response = server.handle(json_rpc_message)          # POST /mcp body in, JSON response out (None: 202)
+```
+
+- A handler returns the value for `structuredContent`; for a job it returns
+  `ctx.start_job()`, and `on_job_started(job_id, ctx)` does or schedules the work.
+- `jobs.request_input(job_id, {"title_choice": fi.choice_request(...)}, "Two titles are ready.")`
+  stops for a person. Fabric answers through `fabric.job.get` with `inputResponses`; the
+  server calls `on_input(job_id, answers, ctx)` with the answers that matched.
+- `jobs.complete(job_id, fi.result_envelope(...))`, `jobs.fail(job_id, code, message)`,
+  `jobs.cancel(job_id)`. A terminal job never changes again.
+- Every result carries `_meta.traceparent`. For a job it is the span of the call that
+  started it, so the result is traced (the contract's FAC-SEM-019 records an untraced
+  result as an incomplete span).
+- Log events about the work with `**fi.trace_ids(ctx.traceparent)` so the pair lands on
+  the event.
+
+`McpToolServer` answers `server/discover`, `tools/list` and `tools/call` with JSON
+responses — enough for Fabric and for the probe. A service already on an MCP SDK keeps
+the SDK and uses only the helpers. The Node kit has the helpers and the same job file
+format, without the dispatcher. `scripts/sample_service.py` is the worked example:
+`sample.echo` answers at once, `sample.draft` is a job that stops for a title choice.
+
+Two readings the contract leaves open, and what the kit does meanwhile:
+
+- a job tool serves the capability's `outputSchema` although its `structuredContent` is
+  the handle (contract OQ-0006);
+- events that belong to no traced work carry no trace pair (contract OQ-0007).
+
+## What the probe checks
+
+`check_service.py` adds these rules; they read, and never call a capability.
+
+| Rule | PASS when | NOT_RUN when |
+|---|---|---|
+| `interop.manifest-link` | the manifest `fabricManifest` names carries the service key with this `<id>.<instance>` (G-07) | the descriptor names no manifest |
+| `interop.well-known-capabilities` | every name in `surfaces.mcp.capabilities` is a manifest capability | the surface lists none |
+| `interop.tools-match` | every `mcp` capability is served as its tool, schemas equal to the files beside the manifest (matched by `$id`), annotations derived | no manifest, no MCP surface, or a schema is not beside the manifest |
+| `interop.job-tools` | a `job: true` capability comes with `fabric.job.get` and `fabric.job.cancel` | no capability is a job |
+| `interop.unknown-job` | `fabric.job.get` for a made-up id answers `isError` with `unknown-job` | `fabric.job.get` is not served |
+| `interop.trace-propagation` | the answer's `_meta.traceparent` has the probe's trace id and a new span | the answer carries no traceparent |
+| `interop.events-trace` | every event with a trace carries both `traceId` and `spanId`, well formed | no events page was read |
+
+`python3 scripts/check_service.py <id>` prints them with the rest; `--json` for a machine.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -1,6 +1,6 @@
 # fabric-service/0.1 — wire reference
 
-Pinned to `fabric-agent-contract` commit `a5a27092ba0dcc5facfbeae8b359146dfb403e9a`
+Pinned to `fabric-agent-contract` commit `a22dea359ba04b8fe549abe81a5131552cb90eff`
 (`docs/specification/service.md`, DEC-0015). The contract's schemas are normative;
 this page is the working summary. Extension key:
 `https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.

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

@@ -8,6 +8,10 @@
 Every rule gets PASS, FAIL or NOT_RUN with its evidence. Exit 0 when nothing
 FAILs, 1 when something does, 2 on a usage error. The probe only reads, except
 that it redeems one login code it asked for itself (that creates one session).
+
+The interop.* rules (fabric-interop/0.1) read the manifest the descriptor names and
+the service's MCP surface: tools/list, and fabric.job.get for an id that does not
+exist. They never call a capability.
 """
 
 from __future__ import annotations
@@ -20,6 +24,7 @@ import os
 from pathlib import Path
 import plistlib
 import re
+import secrets
 import shutil
 import stat
 import subprocess
@@ -29,6 +34,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402
+import fabric_interop as fi  # noqa: E402
 
 Result = Dict[str, str]
 
@@ -42,6 +48,8 @@ class Probe:
         self.results: List[Result] = []
         self.wk: Optional[Dict[str, Any]] = None
         self.token: Optional[str] = None
+        self.events: Optional[List[Dict[str, Any]]] = None
+        self.sent_traceparent: Optional[str] = None
         try:
             self.port = fs.port_of(str(descriptor.get("origin", "")))
         except fs.ServiceError:
@@ -184,6 +192,7 @@ class Probe:
         except (ValueError, KeyError, AssertionError):
             self.add("events.page", "FAIL", "not an events page")
             return
+        self.events = events
         bad = []
         for e in events:
             if e.get("level") not in fs.LEVELS or not re.match(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$", str(e.get("kind", ""))):
@@ -215,6 +224,170 @@ class Probe:
         self.add("login.single-use", "PASS" if ok else "FAIL",
                  "first redeem HTTP %d (%s), second HTTP %d" % (status1, "cookie ok" if "HttpOnly" in cookie else "no HttpOnly cookie", status2))
 
+    # interop (fabric-interop/0.1) ----------------------------------------------------
+    # #region probe-interop — docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/interop.md#what-the-probe-checks
+    def mcp_call(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """One JSON-RPC request to the MCP surface, as a child of a fresh probe trace."""
+        path = (((self.wk or {}).get("surfaces") or {}).get("mcp") or {}).get("path", "/mcp")
+        self.sent_traceparent = fi.child_traceparent(None)
+        body = dict(params)
+        body["_meta"] = {"io.modelcontextprotocol/protocolVersion": fi.MCP_REVISION,
+                         "io.modelcontextprotocol/clientCapabilities": {}, "traceparent": self.sent_traceparent}
+        headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream",
+                   "MCP-Protocol-Version": fi.MCP_REVISION}
+        headers.update(self.auth_headers())
+        message = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": body}).encode()
+        status, resp_headers, raw = self.request("POST", path, headers, message)
+        if status != 200:
+            raise OSError("HTTP %d from %s" % (status, path))
+        if resp_headers.get("content-type", "").startswith("text/event-stream"):
+            data = [line[5:].strip() for line in raw.decode().splitlines() if line.startswith("data:")]
+            raw = (data[-1] if data else "null").encode()
+        return json.loads(raw)
+
+    def load_manifest(self) -> Tuple[Optional[Dict[str, Any]], Optional[Path], str]:
+        named = self.d.get("fabricManifest")
+        if not named:
+            return None, None, "the descriptor names no fabricManifest"
+        try:
+            path = fs.expand(str(named))
+            return json.loads(path.read_text(encoding="utf-8")), path, str(path)
+        except (fs.ServiceError, OSError, ValueError) as exc:
+            return None, None, "manifest %s does not resolve: %s" % (named, exc)
+
+    def resolve_schema(self, manifest_path: Path, uri: str) -> Optional[Dict[str, Any]]:
+        """A schema named by URI, found by its $id among the JSON files beside the manifest. Nothing is fetched."""
+        for candidate in sorted(manifest_path.parent.glob("fabric/schemas/*.json")) + sorted(manifest_path.parent.glob("*.schema.json")):
+            try:
+                doc = json.loads(candidate.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+            if isinstance(doc, dict) and doc.get("$id") == uri:
+                return doc
+        return None
+
+    def interop_rules(self) -> None:
+        manifest, manifest_path, where = self.load_manifest()
+        me = "%s.%s" % (self.d.get("id"), self.d.get("instance", "default"))
+        if manifest is None:
+            self.add("interop.manifest-link", "NOT_RUN" if not self.d.get("fabricManifest") else "FAIL", where)
+        else:
+            block = ((manifest.get("provider") or {}).get("extensions") or {}).get(fs.EXTENSION_KEY) or {}
+            named = block.get("descriptor")
+            self.add("interop.manifest-link", "PASS" if named == me else "FAIL",
+                     "%s names %s" % (where, named) if named else "%s carries no %s block naming %s" % (where, fs.EXTENSION_KEY, me))
+        capabilities = [c for c in (manifest or {}).get("capabilities", []) if isinstance(c, dict)]
+        names = {c.get("name") for c in capabilities}
+        mcp_surface = ((self.wk or {}).get("surfaces") or {}).get("mcp")
+        listed = (mcp_surface or {}).get("capabilities")
+        if listed is None or manifest is None:
+            self.add("interop.well-known-capabilities", "NOT_RUN", "no capability list on the MCP surface" if listed is None else where)
+        else:
+            extra = sorted(set(listed) - names)
+            self.add("interop.well-known-capabilities", "FAIL" if extra else "PASS",
+                     ("listed but not in the manifest: " + ", ".join(extra)) if extra else "%d listed, all in the manifest" % len(listed))
+        if not mcp_surface or not self.token:
+            for rule in ("interop.tools-match", "interop.job-tools", "interop.unknown-job", "interop.trace-propagation"):
+                self.add(rule, "NOT_RUN", "no MCP surface" if not mcp_surface else "no readable token")
+        else:
+            try:
+                listing = self.mcp_call("tools/list", {})
+            except (OSError, ValueError) as exc:
+                self.add("interop.tools-match", "FAIL", "tools/list failed: %s" % exc)
+                listing = None
+            if listing is not None:
+                sent = self.sent_traceparent
+                tools = {t.get("name"): t for t in (listing.get("result") or {}).get("tools", []) if isinstance(t, dict)}
+                self.tools_match_rule(capabilities, manifest_path, tools)
+                self.job_tools_rule(capabilities, tools)
+                self.unknown_job_rule(list(tools))
+                self.trace_rule(listing, sent)
+        self.events_trace_rule(self.events)
+
+    def tools_match_rule(self, capabilities: List[Dict[str, Any]], manifest_path: Optional[Path], tools: Dict[str, Any]) -> None:
+        """FAC-SEM-017: each mcp capability is served as the tool of its name, with its schemas and derived annotations."""
+        served = [c for c in capabilities if (c.get("profile") or {}).get("kind") == "mcp"]
+        if manifest_path is None or not served:
+            self.add("interop.tools-match", "NOT_RUN", "no manifest with an mcp capability")
+            return
+        problems, unresolved = [], []
+        for cap in served:
+            name = cap.get("name")
+            tool = tools.get(name)
+            if tool is None:
+                problems.append("%s is not served as a tool" % name)
+                continue
+            for side in ("inputSchema", "outputSchema"):
+                schema = self.resolve_schema(manifest_path, str(cap.get(side)))
+                if schema is None:
+                    unresolved.append("%s %s" % (name, cap.get(side)))
+                elif tool.get(side) != schema:
+                    problems.append("%s serves an %s that differs from %s" % (name, side, cap.get(side)))
+            annotations = tool.get("annotations") or {}
+            for hint, value in fi.expected_annotations(cap.get("effect", ""), cap.get("idempotency", "")).items():
+                if annotations.get(hint) is not value:
+                    problems.append("%s lacks %s (effect %s, idempotency %s)" % (name, hint, cap.get("effect"), cap.get("idempotency")))
+        if problems:
+            self.add("interop.tools-match", "FAIL", "; ".join(problems))
+        elif unresolved:
+            self.add("interop.tools-match", "NOT_RUN", "schemas not found beside the manifest: " + ", ".join(unresolved))
+        else:
+            self.add("interop.tools-match", "PASS", "%d capabilities served with their schemas and annotations" % len(served))
+
+    def job_tools_rule(self, capabilities: List[Dict[str, Any]], tools: Dict[str, Any]) -> None:
+        jobs = [c.get("name") for c in capabilities if ((c.get("extensions") or {}).get(fi.EXTENSION_KEY) or {}).get("job") is True]
+        if not jobs:
+            self.add("interop.job-tools", "NOT_RUN", "no capability declares job: true")
+            return
+        missing = [n for n in ("fabric.job.get", "fabric.job.cancel") if n not in tools]
+        self.add("interop.job-tools", "FAIL" if missing else "PASS",
+                 ("job capabilities %s, but %s not served" % (", ".join(jobs), " and ".join(missing))) if missing else "fabric.job.get and fabric.job.cancel served")
+
+    def unknown_job_rule(self, tool_names: List[str]) -> None:
+        """C3.2: an unknown id answers isError with unknown-job, never a fresh job."""
+        if "fabric.job.get" not in tool_names:
+            self.add("interop.unknown-job", "NOT_RUN", "fabric.job.get is not served")
+            return
+        probe_id = "probe-unknown-" + secrets.token_hex(6)
+        try:
+            answer = self.mcp_call("tools/call", {"name": "fabric.job.get", "arguments": {"id": probe_id}})
+        except (OSError, ValueError) as exc:
+            self.add("interop.unknown-job", "FAIL", "fabric.job.get failed: %s" % exc)
+            return
+        result = answer.get("result") or {}
+        ok = result.get("isError") is True and "unknown-job" in json.dumps(result)
+        self.add("interop.unknown-job", "PASS" if ok else "FAIL",
+                 "isError with unknown-job for %s" % probe_id if ok else "an unknown id did not answer isError with unknown-job")
+
+    def trace_rule(self, answer: Dict[str, Any], sent: Optional[str]) -> None:
+        """C3.4: work runs as a child span of the caller — same trace, new span."""
+        answered = fi.parse_traceparent(((answer.get("result") or {}).get("_meta") or {}).get("traceparent"))
+        mine = fi.parse_traceparent(sent)
+        if answered is None or mine is None:
+            self.add("interop.trace-propagation", "NOT_RUN", "the answer carries no _meta.traceparent (C3.4 does not require it)")
+        elif answered["trace_id"] == mine["trace_id"] and answered["span_id"] != mine["span_id"]:
+            self.add("interop.trace-propagation", "PASS", "answered as a child span of trace %s" % mine["trace_id"])
+        else:
+            self.add("interop.trace-propagation", "FAIL", "answered with trace %s span %s to a call in trace %s span %s"
+                     % (answered["trace_id"], answered["span_id"], mine["trace_id"], mine["span_id"]))
+
+    def events_trace_rule(self, events: Optional[List[Dict[str, Any]]]) -> None:
+        """C3.4 c: an event about traced work carries traceId and spanId together, well formed."""
+        if events is None:
+            self.add("interop.events-trace", "NOT_RUN", "no events page was read")
+            return
+        bad, traced = [], 0
+        for e in events:
+            has = ("traceId" in e, "spanId" in e)
+            if has == (False, False):
+                continue
+            traced += 1
+            if has != (True, True) or not fi.parse_traceparent("00-%s-%s-01" % (e.get("traceId"), e.get("spanId"))):
+                bad.append(str(e.get("id")))
+        self.add("interop.events-trace", "FAIL" if bad else "PASS",
+                 ("events with a broken trace pair: " + ", ".join(bad)) if bad else "%d of %d events traced, every pair whole" % (traced, len(events)))
+    # #endregion probe-interop
+
     # lifecycle ----------------------------------------------------------------
     def lifecycle_rules(self) -> None:
         life = self.d.get("lifecycle") or {}
@@ -315,6 +488,7 @@ class Probe:
             self.network_rules()
             self.auth_rules()
             self.login_rules()
+            self.interop_rules()
         self.lifecycle_rules()
         return self.results