@passioncode-ai/fabric-agent-adapter 0.81.0 → 0.83.1

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

@@ -17,7 +17,6 @@ Normative source: fabric-agent-contract docs/specification/interop.md (DEC-0016,
 
 from __future__ import annotations
 
-import base64
 import hashlib
 import json
 import math
@@ -98,6 +97,14 @@ from fabric_interop_rules import (  # noqa: E402,F401 - the rule layer (FAA-92)
     pause_message,
     intent_digest,
     repeated_key_decision,
+    NAMED_METHODS,
+    UNREADABLE_AGENT,
+    identified_agent,
+    HEADER_MISMATCH,
+    encode_header_value,
+    decode_header_value,
+    mcp_header_problem,
+    mcp_request_headers,
 )
 
 # --- C3.1 capabilities as tools --------------------------------------------------
@@ -399,6 +406,8 @@ class JobStore:
         A step is kept as the gate reads it (kept_step), so a job's start and its answer agree."""
         if not isinstance(input_requests, dict) or not input_requests:  # a JSON object of requests, first (readings 38, 39)
             raise InteropError("input_required needs a JSON object of at least one input request.")
+        if steps is not None and not isinstance(steps, dict):  # a JSON object or none, in both kits (FAA-196 (26))
+            raise InteropError("steps maps an input request's key to its approval step: a JSON object, or none.")
         kept: Dict[str, Dict[str, Any]] = {}
         for key, step in (steps or {}).items():  # the value checked is the value kept (seam reading 34)
             kept[key] = kept_step(step) if key in input_requests and isinstance(step, dict) else {}
@@ -493,7 +502,8 @@ class CallContext:
     def __init__(self, server: "McpToolServer", tool: str, arguments: Any, traceparent: str,
                  delegation: Optional[Dict[str, Any]] = None, *, tier: Optional[str] = None, caller: Optional[str] = None,
                  meta: Optional[Dict[str, Any]] = None, record: Any = None, decision: Optional[Dict[str, Any]] = None,
-                 input_records: Optional[Dict[str, Any]] = None, mandate: Optional[Dict[str, Any]] = None):
+                 input_records: Optional[Dict[str, Any]] = None, mandate: Optional[Dict[str, Any]] = None,
+                 caller_agent: Optional[str] = None):
         self.server = server
         self.tool = tool
         self.arguments = arguments
@@ -503,12 +513,19 @@ class CallContext:
         self.tier, self.caller, self.meta = tier, caller, {} if meta is None else meta
         self.record, self.decision, self.input_records = record, decision, input_records
         self.mandate = mandate
+        # FAA-135: the caller's agent id the service authenticated (the delegation's caller, else identify_agent's).
+        delegated = (delegation or {}).get("caller")
+        self.caller_agent = caller_agent if caller_agent is not None else (delegated if isinstance(delegated, str) and delegated else None)
 
     def start_job(self, poll_interval_ms: Optional[int] = None) -> Dict[str, Any]:
         if self.server.jobs is None:
             raise InteropError("This server has no job store.")
         handle = self.server.jobs.create(self.tool, self.arguments, self.traceparent, poll_interval_ms, self.delegation)
-        self.server.job_started(handle["job"]["id"], self)
+        try:
+            self.server.job_started(handle["job"]["id"], self)
+        except InteropError as exc:  # a refused start: the job it created ends with it, never left working (FAA-196 (28))
+            self.server.jobs.fail(handle["job"]["id"], "tool-error", str(exc)[:_MAX_ERROR_MESSAGE] or "The job's start was refused.")
+            raise
         return handle
 
     def approval_step(self, job_id: str, key: str, request: Dict[str, Any], *, effect: str, spend_usd: Any = None,
@@ -527,7 +544,7 @@ class CallContext:
         stored = self.server.jobs.private(job_id).get("capability")
         capability = stored if isinstance(stored, str) else self.tool
         if self.server.agent_id is not None:
-            caller = (self.delegation or {}).get("caller")
+            caller = self.caller_agent
             carried = self.meta.get("mandate")
             if carried is None and "mandate" in self.meta:
                 carried = {}  # a null mandate is present and unreadable, as the answer reads it; never "none" (FAA-178)
@@ -550,84 +567,6 @@ JOB_REQUEST_SCHEMA = {"type": "object", "required": ["id"], "additionalPropertie
     "inputResponses": {"type": "object"}}}
 
 
-NAMED_METHODS = {"tools/call": "name", "prompts/get": "name", "resources/read": "uri"}
-HEADER_MISMATCH = -32020  # the code the official 2026-07-28 server SDK answers a header/body mismatch with
-
-
-_SENTINEL = ("=?base64?", "?=")
-
-
-def encode_header_value(value: str) -> str:
-    """A body value as an HTTP header value, by MCP 2026-07-28 Streamable HTTP "Value Encoding": as
-    it is when it is printable ASCII without leading or trailing whitespace, otherwise — and for a
-    plain value that itself looks like the sentinel — `=?base64?<base64 of its UTF-8>?=`."""
-    plain = (all(0x20 <= ord(c) <= 0x7E for c in value) and value == value.strip(" ")
-             and not (value.startswith(_SENTINEL[0]) and value.endswith(_SENTINEL[1])))
-    if plain:
-        return value
-    return _SENTINEL[0] + base64.b64encode(value.encode("utf-8")).decode("ascii") + _SENTINEL[1]
-
-
-def decode_header_value(value: str) -> Optional[str]:
-    """The body value a header carries, decoding the Base64 sentinel; None for a header value with
-    invalid characters or a sentinel that is not valid Base64 of UTF-8 (a server rejects both)."""
-    if value.startswith(_SENTINEL[0]) and value.endswith(_SENTINEL[1]) and len(value) >= len(_SENTINEL[0]) + len(_SENTINEL[1]):
-        try:
-            return base64.b64decode(value[len(_SENTINEL[0]):-len(_SENTINEL[1])], validate=True).decode("utf-8")
-        except ValueError:  # binascii.Error and UnicodeDecodeError are both ValueErrors
-            return None
-    if any(not (0x20 <= ord(c) <= 0x7E or c == "\t") for c in value):
-        return None
-    return value
-
-
-def mcp_header_problem(message: Any, headers: Any) -> Optional[str]:
-    """MCP 2026-07-28 Streamable HTTP mirrors the body in `Mcp-Method` (every request and
-    notification) and `Mcp-Name` (`params.name` or `params.uri` of tools/call, prompts/get,
-    resources/read). A server MUST reject a mismatch; a request that declares 2026-07-28 must
-    carry them. Earlier revisions may omit them, but what they send must still agree.
-    `headers` is any case-insensitive mapping with `.get` (http.server's message, a dict)."""
-    if not isinstance(message, dict) or headers is None:
-        return None
-    def header(name: str) -> Optional[str]:
-        value = headers.get(name) if hasattr(headers, "get") else None
-        if value is None and isinstance(headers, dict):
-            value = next((v for k, v in headers.items() if k.lower() == name.lower()), None)
-        if isinstance(value, (list, tuple)):
-            value = value[0] if value else None
-        return None if value is None else str(value)
-    declared = header("MCP-Protocol-Version") == MCP_REVISION
-    method = message.get("method")
-    sent = header("Mcp-Method")
-    if sent is None and declared:
-        return "the body names method %s but the required Mcp-Method header is absent" % method
-    if sent is not None and sent != method:
-        return "Mcp-Method %s disagrees with the body's method %s" % (sent, method)
-    field = NAMED_METHODS.get(str(method))
-    if field:
-        params = message.get("params")
-        value = params.get(field) if isinstance(params, dict) else None
-        named = header("Mcp-Name")
-        if named is None and declared:
-            return "the body carries params.%s but the required Mcp-Name header is absent" % field
-        if named is not None:
-            decoded = decode_header_value(named)
-            if decoded is None:
-                return "Mcp-Name is malformed: invalid characters or a broken =?base64?…?= value"
-            if decoded != str(value):
-                return "Mcp-Name disagrees with the body's params.%s" % field
-    return None
-
-
-def mcp_request_headers(method: str, params: Dict[str, Any]) -> Dict[str, str]:
-    """The standard headers a 2026-07-28 client sends with one request."""
-    out = {"MCP-Protocol-Version": MCP_REVISION, "Mcp-Method": method}
-    field = NAMED_METHODS.get(method)
-    if field and params.get(field) is not None:
-        out["Mcp-Name"] = encode_header_value(str(params[field]))
-    return out
-
-
 _UNREADABLE = object()  # what a service's spend or project function answers when it raised
 _UNREADABLE_PROJECT = UNREADABLE_PROJECT  # never a member of a mandate's projects, so a scoped mandate refuses
 
@@ -649,7 +588,8 @@ class McpToolServer:
                  approve: Optional[Callable[[str, Dict[str, Any], Any, str], Optional[Dict[str, Any]]]] = None,
                  elicited: Optional[Callable[[str, Dict[str, Any], Optional[str]], bool]] = None,
                  input_actions: bool = False, clock: Callable[[], float] = time.time,
-                 on_fault: Optional[Callable[[str, str], None]] = None, agent_id: Optional[str] = None):
+                 on_fault: Optional[Callable[[str, str], None]] = None, agent_id: Optional[str] = None,
+                 identify_agent: Optional[Callable[[Any, str], Optional[str]]] = None):
         # authorize(tool, headers, tier=) runs before every handler (fabric_delegation.delegation_gate, DEC-0039):
         # a refusal is answered in the DL-19 shape and the handler never runs. The built-in job tools are
         # gated by the job's own capability, and answered only for the principal and caller that started it.
@@ -663,12 +603,14 @@ class McpToolServer:
         # (MJ-1), which the caller reads as operator-decision-required naming it in data.detail.
         # DEC-0125: agent_id is this service's own agent id; with it the server reads a call's _meta.mandate for a
         # relayed action added with its effect (the chain must end in agent_id, and in the delegation's caller before
-        # it when authorize accepted a token); without it a mandate is not read, as before.
+        # it when authorize accepted a token); without it a mandate is not read, as before. FAA-135:
+        # identify_agent(headers, tier) names the agent id of a per-agent credential the service authenticated, read
+        # when no delegation named a caller: the chain must hold it before agent_id (identified_agent reads its answer).
         if agent_id is not None and not is_agent_id(agent_id):
             raise InteropError("agent_id is this service's agent id (a lower-case id, optionally .instance; DEC-0125).")
         self.agent_id = agent_id
         self._authorize = authorize
-        self._identify, self._approve, self._elicited = identify, approve, elicited
+        self._identify, self._approve, self._elicited, self._identify_agent = identify, approve, elicited, identify_agent
         self.input_actions, self._clock, self._on_fault = input_actions is True, clock, on_fault
         self.actions: Dict[str, Dict[str, Any]] = {}
         self.info = {"name": name, "version": version}
@@ -739,6 +681,20 @@ class McpToolServer:
             authenticated = self._identify(headers, tier)
         return action_caller(tier, authenticated)
 
+    def _caller_agent(self, headers: Any, tier: str, verdict: Optional[Dict[str, Any]]) -> Optional[str]:
+        """FAA-135: the caller's agent id a mandate's chain is bound with: the delegation's caller when authorize accepted
+        a token, else what identify_agent names (identified_agent; a hook that raises names UNREADABLE_AGENT), else
+        None. Read only on a server with agent_id; never a name the call carries."""
+        delegated = (verdict or {}).get("caller")
+        if self.agent_id is None or (isinstance(delegated, str) and delegated):
+            return delegated if self.agent_id is not None else None
+        if self._identify_agent is None:
+            return None
+        try:
+            return identified_agent(self._identify_agent(headers, tier))
+        except Exception:  # noqa: BLE001 - the service's own hook: an id no chain holds, so a mandate is refused
+            return UNREADABLE_AGENT
+
     def _gate_action(self, action: Dict[str, Any], name: str, arguments: Dict[str, Any], target: Any, url: Any,
                      headers: Any, tier: str, meta: Dict[str, Any], caller: Optional[str],
                      mandate: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -766,13 +722,12 @@ class McpToolServer:
         return action_gate(action, tier=tier, caller=caller, meta=meta, target=target, elicited=elicited, approval=approval,
                            action_digest=digest, human_step_url=url, now=format_rfc3339(self._clock() * 1000), **(mandate or {}))
 
-    def _mandate_inputs(self, entry: Dict[str, Any], arguments: Dict[str, Any], verdict: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    def _mandate_inputs(self, entry: Dict[str, Any], arguments: Dict[str, Any], caller_agent: Optional[str]) -> Dict[str, Any]:
         """DEC-0125: what action_gate reads a mandate with, empty on a server without agent_id. The caller's agent id is
-        the delegation's caller when authorize accepted a token, never a name the call carries."""
+        _caller_agent's (the delegation's caller, else identify_agent's, FAA-135), never a name the call carries."""
         if self.agent_id is None:
             return {}
         spend, project = (self._read(entry.get(k), arguments) for k in ("spend", "project"))
-        caller_agent = (verdict or {}).get("caller")
         # The estimate is read as a double, as the contract does: an int past the float range is infinite, and an
         # estimate that is not a finite number reads as none, which a mandate's ceiling refuses (fail closed).
         number = _real_number(spend)  # by what it stores; a bool, a mock or not a number is none (seam reading 18)
@@ -799,7 +754,7 @@ class McpToolServer:
             return _UNREADABLE
 
     def _gate_inputs(self, arguments: Dict[str, Any], headers: Any, tier: str, meta: Dict[str, Any],
-                     caller: Optional[str], verdict: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+                     caller: Optional[str], agent: Optional[str] = None) -> Dict[str, Any]:
         """D8: each input request an answer would take is an action (id its key, tool fabric.job.get, gate relayed),
         one decision per call; the first refusal refuses the call and nothing is applied. DEC-0125: on a server with
         agent_id, a step approval_step kept is read under the call's `_meta.mandate` too (C3.3)."""
@@ -818,7 +773,6 @@ class McpToolServer:
                 # A kept step's mandate is read as approval_step read it, under the job's own capability, which must
                 # be a capability name (MJ-1); the action itself stays fabric.job.get, so it is a readable action.
                 capability = private.get("capability")
-                agent = (verdict or {}).get("caller")
                 mandate = {"self_id": self.agent_id, "effect": step.get("effect"), "spend_usd": step.get("spendUsd"),
                            "project": step.get("project"), "caller_agent": agent if isinstance(agent, str) and agent else None,
                            "mandate_capability": capability if isinstance(capability, str) else None}
@@ -921,13 +875,13 @@ class McpToolServer:
                 if not verdict.get("ok"):
                     import fabric_delegation as _fd  # noqa: E402 - only a gated server needs it
                     return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(verdict, traceparent=span)}
-            caller, inputs = self._caller(headers, tier, verdict), None
+            caller, agent, inputs = self._caller(headers, tier, verdict), self._caller_agent(headers, tier, verdict), None
             responses = arguments.get("inputResponses")
             if name == "fabric.job.get" and responses is not None and not isinstance(responses, dict):  # seam r37: never a crash
                 return self._error(rid, -32602, "fabric.job.get takes inputResponses as a JSON object (interop C3.3).")
             if name == "fabric.job.get" and self.input_actions and isinstance(responses, dict) and responses:
                 try:
-                    inputs = self._gate_inputs(arguments, headers, tier, meta, caller, verdict)
+                    inputs = self._gate_inputs(arguments, headers, tier, meta, caller, agent)
                 except UnknownJob:
                     return {"jsonrpc": "2.0", "id": rid, "result": unknown_job_result(str(arguments.get("id", "")), traceparent=span)}
                 if not inputs["ok"] and "invalid" in inputs:
@@ -937,7 +891,8 @@ class McpToolServer:
                     self._fault(stored if isinstance(stored, str) else name, inputs)  # as the start heard it (FAA-179)
                     import fabric_delegation as _fd  # noqa: E402 - DL-19
                     return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(inputs["refusal"], traceparent=span)}
-            context = {"tier": tier, "caller": caller, "meta": meta, "input_records": inputs["records"] if inputs else None}
+            context = {"tier": tier, "caller": caller, "meta": meta, "input_records": inputs["records"] if inputs else None,
+                       "caller_agent": agent}
             return {"jsonrpc": "2.0", "id": rid, "result": self._job_call(name, arguments, span, verdict, context)}
         handler = self.handlers.get(name)
         if handler is None:
@@ -950,9 +905,10 @@ class McpToolServer:
                 return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(verdict, traceparent=span)}
             delegation = verdict
         caller, gated, entry = self._caller(headers, tier, delegation), {"record": None, "decision": None}, self.actions.get(name)
+        agent = self._caller_agent(headers, tier, delegation)
         if entry is not None:  # DEC-0121: after the authorize gate, before the handler
             gated = self._gate_action(entry["action"], name, arguments, self._target(entry["target"], arguments), entry["url"],
-                                      headers, tier, meta, caller, self._mandate_inputs(entry, arguments, delegation))
+                                      headers, tier, meta, caller, self._mandate_inputs(entry, arguments, agent))
             if not gated["ok"] and "invalid" in gated:
                 return self._error(rid, -32602, gated["invalid"])
             if not gated["ok"]:
@@ -960,7 +916,7 @@ class McpToolServer:
                 import fabric_delegation as _fd  # noqa: E402 - DL-19
                 return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(gated["refusal"], traceparent=span)}
         context = CallContext(self, name, arguments, span, delegation, tier=tier, caller=caller, meta=meta,
-                              record=gated["record"], decision=gated["decision"], mandate=gated.get("mandate"))
+                              record=gated["record"], decision=gated["decision"], mandate=gated.get("mandate"), caller_agent=agent)
         try:
             structured = handler(arguments, context)
         except InteropError as exc:
@@ -990,7 +946,10 @@ class McpToolServer:
                 matched = self.jobs.answer(job_id, responses)
                 if matched and self._on_input:
                     private = self.jobs.private(job_id)
-                    self._on_input(job_id, matched, CallContext(self, private["capability"], private["input"], job_span, delegation, **context))
+                    try:
+                        self._on_input(job_id, matched, CallContext(self, private["capability"], private["input"], job_span, delegation, **context))
+                    except InteropError as exc:  # answered as the handler path answers one (FAA-196 (27))
+                        return tool_result({"error": {"code": "tool-error", "message": str(exc)}}, is_error=True, traceparent=job_span)
             return tool_result({"job": self.jobs.get(job_id)}, traceparent=job_span)
         except UnknownJob:
             return unknown_job_result(job_id, traceparent=span)

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

@@ -5,6 +5,7 @@ re-exports every name here. Part of the service kit (FAA-92, split from fabric_i
 only, Python 3.9+."""
 from __future__ import annotations
 
+import base64
 import hashlib
 import json
 import math
@@ -20,7 +21,7 @@ if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from
 from fabric_base import ServiceError  # noqa: E402
 from fabric_actions import action_decision, decision_shape, job_capability  # noqa: E402 - DEC-0121
 from fabric_mandate import (  # noqa: E402 - DEC-0125, DEC-0126
-    EFFECT_CLASSES, OPERATOR_SOURCE_PROTOCOL, mandate_covers, mandate_problem, without_source)
+    EFFECT_CLASSES, OPERATOR_SOURCE_PROTOCOL, is_agent_id, mandate_covers, mandate_problem, without_source)
 
 PROTOCOL = "fabric-interop/0.1"
 EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
@@ -377,6 +378,22 @@ def job_step(mandate: Any, *, tier: Any, now: Any, self_id: Any, capability: Any
 UNREADABLE_PROJECT = "\x00unreadable"
 
 
+#: The caller's agent id when a service's identify_agent hook answered something no chain can hold (an id the registry
+#: refuses, not a string, or the hook raised): passed as callerAgent it matches no agent, so every mandate reads
+#: mandate-not-for-this-call (fail closed, FAA-135). Never an agent id (`is_agent_id` refuses it).
+UNREADABLE_AGENT = "\x00unreadable-agent"
+
+
+def identified_agent(value: Any) -> Optional[str]:
+    """FAA-135: the caller's agent id as a service's own hook named it from a per-agent credential (contract delegation.md,
+    `surfaces.mcp.auth: own`), read as the mandate chain binds it (`callerAgent`): None (no per-agent credential) is
+    none, and the chain's end alone binds the mandate, as before; an agent id the registry accepts is that id; anything
+    else is UNREADABLE_AGENT, which no chain holds. Never a name the call itself carries."""
+    if value is None:
+        return None
+    return value if is_agent_id(value) else UNREADABLE_AGENT
+
+
 def mandate_spend(value: Any) -> Any:
     """A spend estimate as a mandate reads it (FAA-139): a number read as a double, as the contract does; one that is
     not a finite double (an int past the float range, NaN, infinity) or not a number is none, which a mandate's
@@ -559,3 +576,83 @@ def repeated_key_decision(job: Any, now: Any, limit_holds: Optional[bool] = None
         return "same"
     return "run" if "resetsAt" not in data or utc_time(data["resetsAt"]) <= at else "same"
 # #endregion job-limits-kit
+
+
+# --- MCP 2026-07-28 header mirroring (moved from fabric_interop in 0.83.0 to make room under the line ceiling) ---
+
+NAMED_METHODS = {"tools/call": "name", "prompts/get": "name", "resources/read": "uri"}
+HEADER_MISMATCH = -32020  # the code the official 2026-07-28 server SDK answers a header/body mismatch with
+
+
+_SENTINEL = ("=?base64?", "?=")
+
+
+def encode_header_value(value: str) -> str:
+    """A body value as an HTTP header value, by MCP 2026-07-28 Streamable HTTP "Value Encoding": as
+    it is when it is printable ASCII without leading or trailing whitespace, otherwise (and for a
+    plain value that itself looks like the sentinel) `=?base64?<base64 of its UTF-8>?=`."""
+    plain = (all(0x20 <= ord(c) <= 0x7E for c in value) and value == value.strip(" ")
+             and not (value.startswith(_SENTINEL[0]) and value.endswith(_SENTINEL[1])))
+    if plain:
+        return value
+    return _SENTINEL[0] + base64.b64encode(value.encode("utf-8")).decode("ascii") + _SENTINEL[1]
+
+
+def decode_header_value(value: str) -> Optional[str]:
+    """The body value a header carries, decoding the Base64 sentinel; None for a header value with
+    invalid characters or a sentinel that is not valid Base64 of UTF-8 (a server rejects both)."""
+    if value.startswith(_SENTINEL[0]) and value.endswith(_SENTINEL[1]) and len(value) >= len(_SENTINEL[0]) + len(_SENTINEL[1]):
+        try:
+            return base64.b64decode(value[len(_SENTINEL[0]):-len(_SENTINEL[1])], validate=True).decode("utf-8")
+        except ValueError:  # binascii.Error and UnicodeDecodeError are both ValueErrors
+            return None
+    if any(not (0x20 <= ord(c) <= 0x7E or c == "\t") for c in value):
+        return None
+    return value
+
+
+def mcp_header_problem(message: Any, headers: Any) -> Optional[str]:
+    """MCP 2026-07-28 Streamable HTTP mirrors the body in `Mcp-Method` (every request and
+    notification) and `Mcp-Name` (`params.name` or `params.uri` of tools/call, prompts/get,
+    resources/read). A server MUST reject a mismatch; a request that declares 2026-07-28 must
+    carry them. Earlier revisions may omit them, but what they send must still agree.
+    `headers` is any case-insensitive mapping with `.get` (http.server's message, a dict)."""
+    if not isinstance(message, dict) or headers is None:
+        return None
+    def header(name: str) -> Optional[str]:
+        value = headers.get(name) if hasattr(headers, "get") else None
+        if value is None and isinstance(headers, dict):
+            value = next((v for k, v in headers.items() if k.lower() == name.lower()), None)
+        if isinstance(value, (list, tuple)):
+            value = value[0] if value else None
+        return None if value is None else str(value)
+    declared = header("MCP-Protocol-Version") == MCP_REVISION
+    method = message.get("method")
+    sent = header("Mcp-Method")
+    if sent is None and declared:
+        return "the body names method %s but the required Mcp-Method header is absent" % method
+    if sent is not None and sent != method:
+        return "Mcp-Method %s disagrees with the body's method %s" % (sent, method)
+    field = NAMED_METHODS.get(str(method))
+    if field:
+        params = message.get("params")
+        value = params.get(field) if isinstance(params, dict) else None
+        named = header("Mcp-Name")
+        if named is None and declared:
+            return "the body carries params.%s but the required Mcp-Name header is absent" % field
+        if named is not None:
+            decoded = decode_header_value(named)
+            if decoded is None:
+                return "Mcp-Name is malformed: invalid characters or a broken =?base64?…?= value"
+            if decoded != str(value):
+                return "Mcp-Name disagrees with the body's params.%s" % field
+    return None
+
+
+def mcp_request_headers(method: str, params: Dict[str, Any]) -> Dict[str, str]:
+    """The standard headers a 2026-07-28 client sends with one request."""
+    out = {"MCP-Protocol-Version": MCP_REVISION, "Mcp-Method": method}
+    field = NAMED_METHODS.get(method)
+    if field and params.get(field) is not None:
+        out["Mcp-Name"] = encode_header_value(str(params[field]))
+    return out

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

@@ -1,5 +1,15 @@
 """One copy of a service, locked before any side effect (LC-01, DEC-0057): the instance lock, the supervisor marker
-in both its forms, and the wait budget under a supervisor. Part of the service kit (FAA-65, layer L3)."""
+in both its forms, and the wait budget under a supervisor. Part of the service kit (FAA-65, layer L3).
+
+A lock that moves under its holder (FAA-303). Linux and Windows hold a name keyed by the lock's path beside the file
+lock (an abstract unix socket, a named pipe), so a folder swapped under a running copy cannot let a second copy in.
+macOS has no such name: flock (and the Node twin's O_EXLOCK) lock an inode, so after a data import swaps the data
+folder a second copy locks the new file and starts. There the holder watches its lock instead
+(``InstanceLock.watch``, started by ``hold_single_instance``): every ``LOCK_WATCH_SECONDS`` it compares the inode it
+locked with the file at the path, and once the path names another file it stops with 75 and one sentence naming the
+path, before writing anything more into a folder that is no longer the one it read. Two copies then overlap for at
+most one interval. A path-keyed name on macOS was weighed and left: it needs a file in a folder outside the data folder
+that the system never cleans and every copy can write, which the standard library cannot promise."""
 from __future__ import annotations
 
 import errno
@@ -10,6 +20,7 @@ import posixpath
 import re
 import socket
 import sys
+import threading
 import time
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Sequence
@@ -46,6 +57,11 @@ LOCK_BACKOFF_FIRST_SECONDS = 0.5
 LOCK_BACKOFF_MAX_SECONDS = 30.0
 
 
+#: How often a holder that has no path-keyed name (macOS) compares the inode it locked with the file at the lock's
+#: path (FAA-303): one stat and one fstat; two copies overlap for at most this long after a folder swap.
+LOCK_WATCH_SECONDS = 2.0
+
+
 class AlreadyRunning(ServiceError):
     def __init__(self, holder_pid: Optional[int], lock_path: Path):
         self.holder_pid = holder_pid
@@ -67,6 +83,7 @@ class InstanceLock:
         self.path = Path(data_dir) / "service.lock"
         self._fd: Optional[int] = None
         self._name: Any = None
+        self._watch: Optional[threading.Event] = None
 
     #: Windows locks a byte range, not the file: one byte far past the pid the file holds, so the
     #: holder may rewrite the pid and another process may still read it (locking past the end of
@@ -157,13 +174,72 @@ class InstanceLock:
         self._fd = fd
         return True
 
+    def watch(self, on_lost: Optional[Callable[["InstanceLock"], None]] = None,
+              interval: float = LOCK_WATCH_SECONDS) -> "InstanceLock":
+        """Re-check, every ``interval`` seconds on a daemon thread, that the file this copy locked is still the file at
+        the path (FAA-303); the first time the path names another file (a swapped folder's lock, or the one a second
+        copy made), call ``on_lost(lock)`` once and stop watching. The default stops the process with 75 and one
+        sentence (``stop_lost_holder``): it runs on the watch thread, so it cannot raise into the service. A path that
+        is gone or cannot be read now is read as nothing there yet and tried again next time: a second copy has to make
+        a file there to start, and the watch then sees that file. ``release`` ends the watch. Windows does not rename a
+        folder holding an open file: there it is a no-op, as for a lock not held."""
+        if WINDOWS or self._fd is None or self._watch is not None:
+            return self
+        fd, stop, react = self._fd, threading.Event(), on_lost or stop_lost_holder
+
+        def run() -> None:
+            while not stop.wait(interval):
+                try:
+                    here, held = os.stat(str(self.path)), os.fstat(fd)
+                except OSError:
+                    continue
+                # release() sets the event before it closes the descriptor, so a number reused after the close is never
+                # read as this lock's file: the event is checked after the stat.
+                if (here.st_dev, here.st_ino) == (held.st_dev, held.st_ino) or stop.is_set():
+                    continue
+                stop.set()
+                react(self)
+                return
+
+        self._watch = stop
+        threading.Thread(target=run, name="fabric-lock-watch", daemon=True).start()
+        return self
+
     def release(self) -> None:
-        if self._fd is not None:
-            os.close(self._fd)
-            self._fd = None
-        if self._name is not None:
-            _drop_lock_name(self._name)
-            self._name = None
+        """Let the lock go. Never raises, so a release in a `finally` never replaces the caller's own outcome (FAA-196
+        (11)): the descriptor number and the name are forgotten before they are closed, so a retry never closes a
+        number reused since; a close that fails (a deferred write error) still drops the name, as acquire does."""
+        if self._watch is not None:
+            self._watch.set()
+            self._watch = None
+        fd, name, self._fd, self._name = self._fd, self._name, None, None
+        try:
+            if fd is not None:
+                os.close(fd)
+        except OSError:  # the descriptor is gone either way; the kernel frees the lock with it
+            pass
+        finally:
+            if name is not None:
+                try:
+                    _drop_lock_name(name)
+                except OSError:  # nothing to add to the caller's own outcome
+                    pass
+
+
+def lost_lock_message(lock_path: Path) -> str:
+    """The one sentence a holder whose lock moved under it stops with (FAA-303)."""
+    return ("%s is no longer the file this copy locked (the data folder moved or was swapped?): stopping, so a copy "
+            "started on the folder now at that path runs alone." % lock_path)
+
+
+def stop_lost_holder(lock: InstanceLock) -> None:
+    """``InstanceLock.watch``'s default: print ``lost_lock_message`` and end the process with 75 at once. ``os._exit``,
+    not a graceful stop: a shutdown would write this copy's state into the folder now at the path, which is not the
+    one it read; the kit's journals make an abrupt stop recoverable (LC-03)."""
+    try:
+        print(lost_lock_message(lock.path), file=sys.stderr, flush=True)
+    finally:
+        os._exit(EXIT_ALREADY_RUNNING)
 
 
 def lock_name(lock_path: Path, platform: str = sys.platform) -> Optional[str]:
@@ -329,7 +405,8 @@ def add_supervisor_argument(parser: Any) -> Any:
 def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *,
                          sleep: Callable[[float], None] = time.sleep,
                          clock: Callable[[], float] = time.monotonic,
-                         env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> InstanceLock:
+                         env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None,
+                         on_lost: Optional[Callable[[InstanceLock], None]] = None) -> InstanceLock:
     """Take the lock or exit 75 with one sentence naming the holder (DEC-0057, FAC-SEM-078).
 
     Markers that disagree exit 75 at once, before the lock, naming them. Started by hand (no
@@ -337,7 +414,10 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
     exit is a respawn every few seconds, forever; so a supervised copy first backs off in-process
     (0.5 s doubling to 30 s, ``LOCK_WAIT_SUPERVISED_SECONDS`` in all), takes over if the holder
     leaves, and exits 75 only when the wait runs out. Nothing has been touched while it waits.
-    ``wait_seconds`` overrides the choice (0 = never wait); ``env`` and ``argv`` default to this process's."""
+    ``wait_seconds`` overrides the choice (0 = never wait); ``env`` and ``argv`` default to this process's.
+
+    Where the lock has no path-keyed name (macOS) the held lock is watched (``InstanceLock.watch``, FAA-303): a folder
+    swapped under the running copy stops it with 75; ``on_lost`` replaces that reaction."""
     marker = supervisor_marker(env, argv)
     if marker["kind"] == "conflict":
         print(marker_conflict_message(marker), file=sys.stderr)
@@ -349,7 +429,7 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
     announced = False
     while True:
         try:
-            return InstanceLock(data_dir).acquire()
+            lock = InstanceLock(data_dir).acquire()
         except AlreadyRunning as exc:
             remaining = deadline - clock()
             if remaining <= 0:
@@ -360,3 +440,5 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
                 announced = True
             sleep(min(delay, remaining))
             delay = min(delay * 2, LOCK_BACKOFF_MAX_SECONDS)
+            continue
+        return lock.watch(on_lost) if lock_name(lock.path) is None else lock

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

@@ -72,6 +72,45 @@ def vendor(model: str) -> str:
     return str(model).split("/", 1)[0] if "/" in str(model) else ""
 
 
+#: A base URL's path as both twins send it unchanged: URL path characters and %XX escapes only (FAA-187 (18)).
+_BASE_PATH = re.compile(r"(?:/(?:[A-Za-z0-9._~!$&'()*+,;=:@-]|%[0-9A-Fa-f]{2})*)*", re.ASCII)
+
+
+def _dialed_host(base: str) -> str:
+    """The base with a host outside ASCII written as urllib dials it, in IDNA (lower case), so attribution reads the
+    host the call reaches, as the Node twin's `new URL` does (FAA-187 (19)): `openrouter.ai` behind a zero-width space
+    or a soft hyphen is openrouter.ai. check_url has already refused a host the codec cannot write."""
+    scheme, sep, rest = base.partition("://")
+    authority, slash, path = rest.partition("/")
+    userinfo, at, hostport = authority.rpartition("@")
+    if not sep or hostport.isascii() or hostport.startswith("["):
+        return base
+    host, colon, port = hostport.partition(":")
+    return "%s://%s%s%s%s%s%s" % (scheme, userinfo, at, host.encode("idna").decode("ascii").lower(), colon, port, slash + path)
+
+
+def base_url_problem(base: str) -> Optional[str]:
+    """Why a base URL is not sent the same by both twins, read from the URL as sent (its ends trimmed, as `new URL` and
+    urllib trim them), or None: a backslash anywhere (`new URL` reads it as a slash), and after a `//` authority a
+    path holding anything but URL path characters and %XX escapes (Python refused a space or a character outside
+    ASCII, Node sent it percent-encoded; Node removes a tab or a line break) or a dot segment, escaped or not (Node
+    collapses it). The Node twin's `baseUrlProblem` is the same rule (FAA-187 (18), kit-openrouter-cases.json)."""
+    text = base.strip("".join(map(chr, range(0x21))))
+    if "\\" in text:
+        return "the base URL holds a backslash"
+    if any(c in text for c in "\t\n\r"):  # Node's URL parser removes them anywhere and sends the rest
+        return "the base URL holds a tab or a line break"
+    rest = text.partition(":")[2]
+    if not rest.startswith("//"):
+        return None  # no authority as written: check_url reads it
+    path = "/" + rest[2:].partition("/")[2] if "/" in rest[2:] else ""
+    if not _BASE_PATH.fullmatch(path):
+        return "the base URL's path holds a character outside URL path characters and %XX escapes"
+    if any(re.sub("%2[eE]", ".", seg) in (".", "..") for seg in path.split("/")[1:]):
+        return "the base URL's path holds a dot segment"
+    return None
+
+
 _DECIMAL = re.compile(r"(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?", re.ASCII)
 
 
@@ -170,6 +209,9 @@ class Client:
             raise fabric_http.HttpError("the URL does not parse", url="<unparseable url>", kind="refused")
         if "?" in base_url or "#" in base_url:
             raise OpenRouterError("the base URL holds no query or fragment", kind="config")
+        problem = base_url_problem(base_url)
+        if problem:
+            raise OpenRouterError(problem + " (both kits would not send it alike)", kind="config")
         fabric_http.check_url(base_url)
         _check_attribution(project_id, None)
         self.ceiling_usd = float(ceiling_usd)
@@ -179,7 +221,7 @@ class Client:
         self.window = window
         # The base URL as check_url read it and urllib would send it: its ends trimmed, so `.../v1\n` is not sent
         # as `.../v1\n/chat/completions` (0.56.0 seam r18; the Node twin trims the ends `new URL` does, product r20).
-        self.base_url = base_url.strip(fabric_http._URL_ENDS).rstrip("/")
+        self.base_url = _dialed_host(base_url.strip(fabric_http._URL_ENDS).rstrip("/"))
         self.attribution = attribution
         self.project_id = project_id
         self.unmeasured_call_usd = unmeasured_call_usd