@passioncode-ai/fabric-agent-adapter 0.78.0 → 0.80.2

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

@@ -13,7 +13,8 @@ not re-export this module, so a service that does not run per context keeps the
 An organization's instance whose context the record does not pin (``organizations``, DEC-0127) still starts: the helper
 checks the placement and its share grant, not the pin (decision D5 of 0.52.0). Its tokens are refused instead:
 ``fabric_estate.hub_key_certified`` reads a context's hub keys only while the record pins that organization (DL-14a,
-DEC-0128), so the service passes ``estate_context=info["context"]`` to its delegation gate. The contract lets Fabric
+DEC-0128), so the service passes ``context_gate_options(info, record)`` (its context and its pin's issuer, FAA-150) to its
+delegation gate. The contract lets Fabric
 write ``organizations`` only once every reader is pinned at or after DEC-0127, so a refusal at start would stop every
 organization instance on today's records."""
 from __future__ import annotations
@@ -33,7 +34,8 @@ if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from
 from fabric_base import ServiceError, _INSTANCE  # noqa: E402
 from fabric_descriptor import descriptor_path  # noqa: E402
 from fabric_estate import parse_context  # noqa: E402
-from fabric_lock import InstanceLock, hold_single_instance  # noqa: E402
+from fabric_lock import (InstanceLock, LOCK_BACKOFF_FIRST_SECONDS, LOCK_BACKOFF_MAX_SECONDS, hold_single_instance,  # noqa: E402
+                         lock_wait_budget_seconds, supervisor_marker)
 from fabric_paths import atomic_write, instance_dirs  # noqa: E402
 from fabric_share import instance_share_grant  # noqa: E402
 from fabric_time import clock_ms  # noqa: E402
@@ -125,9 +127,49 @@ def context_instance(service_id: str, context: Any, *, record: Optional[Dict[str
     return answer
 
 
-def _refuse(service_id: Any, context: Any, code: str) -> None:
-    print("%s will not run for %s (%s): %s." % (service_id, _shown(context), code, _REASONS[code]), file=sys.stderr, flush=True)
-    raise SystemExit(EXIT_CONTEXT_REFUSED)
+def context_gate_options(info: Any, record: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """What ``delegation_gate`` takes from this instance's context (FAA-150): ``estate_context``, and for an organization
+    whose context ``record`` pins, ``issuer``: the pin's context issuer (DL-14a, DEC-0128), so an organization's instance
+    refuses a token the personal hub key signed without wiring either by hand. ``info`` is ``context_instance``'s answer
+    (or ``hold_context_instance``'s); ``record`` the verified estate revision applied. Spread it after the service's own
+    estate issuer: ``delegation_gate(..., **{"issuer": estate_issuer, **context_gate_options(info, record)})``. Raises
+    ContextRefused (``context-invalid``) for an answer with no context."""
+    context = info.get("context") if isinstance(info, dict) else None
+    parsed = parse_context(context)
+    if parsed is None:
+        raise ContextRefused("context-invalid")
+    options: Dict[str, Any] = {"estate_context": context}
+    pins = record.get("organizations") if isinstance(record, dict) else None
+    if parsed["kind"] == "org" and isinstance(pins, list):
+        for pin in pins:
+            if isinstance(pin, dict) and pin.get("org") == context and isinstance(pin.get("iss"), str):
+                options["issuer"] = pin["iss"]
+                break
+    return options
+
+
+def _refuse(service_id: Any, context: Any, code: str, wait_seconds: Optional[float] = 0.0, *,
+            sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic,
+            env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> None:
+    """One sentence naming the code, then exit 78. Under a supervisor that restarts on exit (launchd's KeepAlive with
+    ThrottleInterval 10, systemd's Restart=always) an exit at once is a respawn every few seconds, forever (FAA-279);
+    so a supervised copy first waits the lock's back-off (0.5 s doubling to 30 s, 300 s in all), holding nothing, and
+    exits 78 when it runs out: a few restarts an hour. ``wait_seconds`` overrides the choice as the lock's does."""
+    if wait_seconds is None:
+        wait_seconds = lock_wait_budget_seconds(supervisor_marker(env, argv))
+    wait_seconds = max(0.0, wait_seconds)
+    tail = " Waiting %.0f s before exiting, so its supervisor does not restart it every few seconds." % wait_seconds \
+        if wait_seconds > 0 else ""
+    print("%s will not run for %s (%s): %s.%s" % (service_id, _shown(context), code, _REASONS[code], tail),
+          file=sys.stderr, flush=True)
+    deadline = clock() + wait_seconds
+    delay = LOCK_BACKOFF_FIRST_SECONDS
+    while True:
+        remaining = deadline - clock()
+        if remaining <= 0:
+            raise SystemExit(EXIT_CONTEXT_REFUSED)
+        sleep(min(delay, remaining))
+        delay = min(delay * 2, LOCK_BACKOFF_MAX_SECONDS)
 
 
 def _marker_matches(path: Path, expected: Dict[str, str]) -> Optional[bool]:
@@ -152,7 +194,7 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
                           env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None,
                           services_directory: Optional[Path] = None) -> Tuple[Dict[str, Any], InstanceLock]:
     """Run as ``context``'s one instance, before any side effect (brief D17): ``context_instance`` (a refusal prints one
-    sentence naming the code and exits 78, nothing created); then ``hold_single_instance`` on the instance's data
+    sentence naming the code and exits 78, nothing created; a supervised copy backs off first, FAA-279); then ``hold_single_instance`` on the instance's data
     folder (its markers, its supervised wait, its exit 75); then the marker ``<data>/fabric-context.json``: absent, it
     is written (0600, atomic); equal, it is kept; another context or instance, or unreadable, releases the lock and
     exits 78 (``context-mismatch``). Returns the instance and the held lock."""
@@ -160,7 +202,7 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
         info = context_instance(service_id, context, record=record, machine_id=machine_id, agent_ref=agent_ref, at=at,
                                 personal_instance=personal_instance, services_directory=services_directory)
     except ContextRefused as refused:
-        _refuse(service_id, context, refused.code)
+        _refuse(service_id, context, refused.code, wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     lock = hold_single_instance(info["dirs"]["data"], wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     expected = {"service": service_id, "instance": info["instance"], "context": context}
     marker = Path(info["dirs"]["data"]) / CONTEXT_MARKER
@@ -173,5 +215,5 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
         raise
     if matches is False:
         lock.release()
-        _refuse(service_id, context, "context-mismatch")
+        _refuse(service_id, context, "context-mismatch", wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     return info, lock

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

@@ -45,6 +45,7 @@ from fabric_jsvalue import (  # noqa: E402 - the core (FAA-65)
     jcs,
 )
 from fabric_paths import atomic_write as _atomic_write  # noqa: E402 - the kit's private writer (FAA-85)
+import fabric_peer_owner as _po  # noqa: E402 - a loopback key set is read from this account's listener only (FAA-255)
 from fabric_mandate import effect_closure  # noqa: E402,F401 - defined once beside the mandate that reads it too (DEC-0125)
 
 REFUSAL_CODES = (
@@ -672,9 +673,21 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
         return None
 
 
-def _opener(deadline: Dict[str, Any]) -> urllib.request.OpenerDirector:
+class _CheckedHTTPConnection(_po.CheckedHTTPConnection):
+    """Plain http, which a key set source allows on loopback only (DEC-0154 HA-2, FAA-255): every connect, a reconnect
+    included, tells the server end's owner and refuses (closed, nothing sent) unless it is this OS account's process,
+    so keys another account's listener serves are never read; built the way urllib builds a connection."""
+
+    def __init__(self, host: str, port: Optional[int] = None, timeout: Any = 10.0, **kwargs: Any) -> None:
+        http.client.HTTPConnection.__init__(self, host, port, timeout=timeout, **kwargs)
+        self.expect_pid = None
+        self.vouch_pid = None  # an issuer's URL is never a process this caller started (FAA-267)
+
+
+def _opener(deadline: Dict[str, Any], direct: bool = False) -> urllib.request.OpenerDirector:
     """No redirect, and a timer that shuts the socket down at the deadline: a socket timeout bounds one read, so an
-    issuer trickling a byte a second would otherwise hold the caller for as long as it likes (finding 13)."""
+    issuer trickling a byte a second would otherwise hold the caller for as long as it likes (finding 13). `direct`:
+    a loopback source never goes through a proxy from the environment, so the owner check reads the URL's own port."""
     def watched(base: type) -> type:
         class Watched(base):  # type: ignore[misc, valid-type]
             def connect(self) -> None:
@@ -695,11 +708,13 @@ def _opener(deadline: Dict[str, Any]) -> urllib.request.OpenerDirector:
 
     class Http(urllib.request.HTTPHandler):
         def http_open(self, req: Any) -> Any:
-            return self.do_open(watched(http.client.HTTPConnection), req)
+            return self.do_open(watched(_CheckedHTTPConnection), req)  # http is loopback only (the source check)
 
     class Https(urllib.request.HTTPSHandler):
         def https_open(self, req: Any) -> Any:
             return self.do_open(watched(http.client.HTTPSConnection), req, context=self._context)
+    if direct:
+        return urllib.request.build_opener(urllib.request.ProxyHandler({}), _NoRedirect, Http, Https)
     return urllib.request.build_opener(_NoRedirect, Http, Https)
 
 
@@ -709,7 +724,8 @@ def _fetch(source: str) -> Any:
         request = urllib.request.Request(source.partition("#")[0], headers={"Accept": "application/json"})
         deadline: Dict[str, Any] = {"end": time.monotonic() + JWKS_FETCH_SECONDS, "fired": False, "timer": None}
         try:
-            with _opener(deadline).open(request, timeout=JWKS_FETCH_SECONDS) as response:  # https or loopback http only
+            direct = source.lower().startswith("http://")
+            with _opener(deadline, direct).open(request, timeout=JWKS_FETCH_SECONDS) as response:  # https or loopback http only
                 body = b""
                 while len(body) <= 65536 and not deadline["fired"]:
                     chunk = response.read1(65537 - len(body))
@@ -724,6 +740,8 @@ def _fetch(source: str) -> Any:
             raise
         except http.client.HTTPException as exc:  # a garbage status line or headers: the issuer cannot be read
             raise ConnectionError(type(exc).__name__) from None
+        except _po.ListenerRefused as exc:  # FAA-255: another account's listener, or one that cannot be told
+            raise ConnectionError("foreign-user: %s" % exc) from None
         finally:
             if deadline["timer"] is not None:
                 deadline["timer"].cancel()

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

@@ -1,5 +1,6 @@
 """How a service is found (fabric-service/0.1): its descriptor, peers and app descriptors (DEC-0061, DEC-0069),
 build identity and the well-known document, the loopback HTTP server. Part of the service kit (FAA-65, layer L3)."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import hashlib
@@ -7,6 +8,7 @@ import http.server
 import json
 import os
 import re
+import socket
 import socketserver
 import subprocess
 import warnings
@@ -18,6 +20,7 @@ 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))
 from fabric_base import (
+    PRIMARY_CAPABILITY,
     PROTOCOL,
     ServiceError,
     _ID,
@@ -28,6 +31,7 @@ from fabric_base import (
     expand,
     now_iso,
 )
+import fabric_peer_owner  # noqa: E402 - L0: who listens on a port (DEC-0154 HA-2, FAA-225)
 from fabric_paths import (
     atomic_write,
     ensure_private_dir,
@@ -49,7 +53,7 @@ from fabric_usage import (
 DASHBOARD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1"
 
 
-DASHBOARD_KIT = "fabric-dashboard-kit@1.1.5"
+DASHBOARD_KIT = "fabric-dashboard-kit@1.1.6"
 
 
 REFERENCE_THEMES = ("graphite", "fabric", "paper", "forest", "ocean", "ember", "contrast")
@@ -476,8 +480,35 @@ def source_refusal(descriptor: Dict[str, Any], directory: Optional[Path] = None)
     return "Descriptor %s %s. %s" % (me, NO_SOURCE_REPOSITORY, PASS_SOURCE)
 
 
-def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = None, *, _stacklevel: int = 2) -> Path:
-    """Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim).
+def port_owner(port: int) -> Optional[Tuple[str, Optional[int]]]:
+    """Who listens on 127.0.0.1:<port> now, as (kind, uid) from the kit's fabric_peer_owner, or None when a plain bind
+    of that address succeeds (nothing holds it, and the socket table is not read). FAA-225, DEC-0154 HA-2."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        try:
+            probe.bind(("127.0.0.1", port))
+            return None
+        except OSError:
+            pass
+    owner = fabric_peer_owner.listener(port)
+    return owner.kind, owner.uid
+
+
+def port_listener_refusal(port: int, reader: Optional[Any] = None) -> Optional[str]:
+    """Why an install may not take ``port``: another OS account listens on it (FAA-225). This account, the system
+    (launchd holds a socket-activated job's socket), nobody and an unreadable table pass: the refusal is for a port
+    that is surely another account's. The recorded port per account and its claim file wait on contract DEC-0160."""
+    found = (reader or port_owner)(port)
+    if not found or found[0] != fabric_peer_owner.ANOTHER_ACCOUNT:
+        return None
+    uid = " (uid %d)" % found[1] if isinstance(found[1], int) else ""
+    return ("Port %d is listened on by another OS account%s: choose a port no other account holds (DEC-0154, "
+            "FAA-225)." % (port, uid))
+
+
+def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = None, *, _stacklevel: int = 2,
+                     port_owner: Optional[Any] = None) -> Path:
+    """Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim), and a port another
+    OS account listens on (FAA-225; ``port_owner(port) -> (kind, uid) | None`` reads it, the kit's own by default).
 
     FAA-198: a new descriptor names its ``source.repository``; rewriting one already installed without it only
     warns (``NoSourceRepositoryWarning``), so an installed agent's update keeps working."""
@@ -504,6 +535,9 @@ def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = Non
             continue
         if other_port == port:
             raise ServiceError("Port %d is already claimed by %s (%s)." % (port, key, path))
+    held = port_listener_refusal(port, port_owner) if port is not None else None
+    if held:
+        raise ServiceError(held)
     ensure_private_dir(root)
     target = descriptor_path(descriptor["id"], descriptor["instance"], root)
     atomic_write(target, (json.dumps(descriptor, indent=2, ensure_ascii=False) + "\n").encode(), 0o600)
@@ -628,6 +662,11 @@ def configuration_problems(doc: Any) -> List[str]:
     return problems
 
 
+#: FAA-244: DEC-0140 PR-1 reserves the primary responder's capability; a service never publishes it.
+_RESERVED = ("%%s: %s is reserved for a Project's primary responder, a session (DEC-0140 PR-1); a service never "
+             "serves it as a tool or declares it." % PRIMARY_CAPABILITY)
+
+
 def build_well_known(*, service_id: str, instance: str, name: str, version: str, build: Dict[str, Any],
                      started_at: str, status: str, degraded: Sequence[Dict[str, str]],
                      surfaces: Dict[str, Any], summary: Optional[Sequence[Dict[str, Any]]] = None,
@@ -664,6 +703,10 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
         problems = a2a_surface_problems(surfaces["a2a"])
         if problems:
             raise ServiceError("surfaces.a2a: %s." % "; ".join(problems))
+    mcp_surface = surfaces.get("mcp")
+    listed = mcp_surface.get("capabilities") if isinstance(mcp_surface, dict) else None
+    if isinstance(listed, list) and PRIMARY_CAPABILITY in listed:
+        raise ServiceError(_RESERVED % "surfaces.mcp.capabilities")
     doc: Dict[str, Any] = {
         "protocol": PROTOCOL,
         "service": {"id": service_id, "instance": instance, "name": name, "version": version, "build": build},
@@ -698,6 +741,9 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
                                                 "surfaces": surfaces})
             if findings:
                 raise ServiceError("Actions declaration: %s." % "; ".join(f["message"] for f in findings))
+            if any(isinstance(a, dict) and a.get("tool") == PRIMARY_CAPABILITY
+                   for a in extensions[ACTIONS_EXTENSION_KEY].get("actions") or []):
+                raise ServiceError(_RESERVED % "an action's tool")
         doc["extensions"] = dict(extensions)
     if configuration is not None:
         problems = configuration_problems(configuration)

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

@@ -28,6 +28,7 @@ The transport is injected in tests: `transport(method, url, headers, body, timeo
 `(status, headers, body_bytes)` or raises `OSError` (a connection error, `TimeoutError` included) or `HttpError`.
 Standard library only. Part of the service kit (FAA-65, layer L4).
 """
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import datetime as _dt
@@ -64,7 +65,7 @@ class HttpError(Exception):
     refused URL or a body over the cap; `url` is redacted; `body` holds at most 2048 bytes of an answer's body."""
 
     def __init__(self, message: str, *, status: Optional[int] = None, url: str = "", attempts: int = 0,
-                 retry_after_s: Optional[float] = None, body: bytes = b"", kind: str = "http"):
+                 retry_after_s: Optional[float] = None, body: bytes = b"", kind: str = "http", reason: Optional[str] = None):
         super().__init__(message)
         self.status = status
         self.url = url
@@ -72,6 +73,9 @@ class HttpError(Exception):
         self.retry_after_s = retry_after_s
         self.body = bytes(body[:2048])
         self.kind = kind  # http (an answer), connection, timeout, too-large, refused, foreign-user
+        #: For foreign-user, why (FAA-272): `table-restricted` (this process sees no other process's sockets, which
+        #: never clears), the owner's kind (`another-account`, `system`) or the check's reason (`no-row`).
+        self.reason = reason
 
 
 class Response:
@@ -385,7 +389,10 @@ def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optio
         return _send(req, timeout_s, max_bytes, end, watchdog)
     except _po.ListenerRefused as exc:
         where = "%s %s" % (method, redact_url(url))
-        raise HttpError("%s: foreign-user: %s" % (where, exc), url=redact_url(url), kind="foreign-user") from None
+        owner = getattr(exc, "owner", None)
+        why = str(getattr(owner, "reason", None) or getattr(owner, "kind", None) or getattr(exc, "code", "") or "unknown")
+        reason = _po.TABLE_RESTRICTED if why.startswith(_po.TABLE_RESTRICTED) else why.split(":", 1)[0]
+        raise HttpError("%s: foreign-user: %s" % (where, exc), url=redact_url(url), kind="foreign-user", reason=reason) from None
     except (OSError, http.client.HTTPException) as exc:
         if watchdog.fired:
             raise TimeoutError("the answer did not arrive within the deadline")

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

@@ -67,6 +67,20 @@ class HubError(Exception):
         return "HubError(%r, %r)" % (self.code, self.message)
 
 
+def listener_refusal(exc: Any) -> HubError:
+    """The HubError for a hub port the peer-owner check refused (DEC-0154 HA-2): code `foreign-user`, the pinned
+    contract's state name, with the owner's reason in the sentence and in `data.reason` (FAA-272): `table-restricted`
+    when this process's socket table hides other processes' sockets, which never clears, so it is not retryable;
+    otherwise the owner's kind or the check's reason (`another-account`, `no-row`), retryable as before."""
+    owner = getattr(exc, "owner", None)
+    why = (getattr(owner, "reason", None) or getattr(owner, "kind", None) or getattr(exc, "code", None) or "unknown")
+    reason = _po.TABLE_RESTRICTED if str(why).startswith(_po.TABLE_RESTRICTED) else str(why).split(":", 1)[0]
+    kind = getattr(owner, "kind", None)
+    shown = "%s: %s" % (kind, owner.reason) if kind and getattr(owner, "reason", None) else str(kind or why)
+    return HubError("foreign-user", "The hub's port is not held by this OS account's process (%s); nothing was sent." % shown,
+                    reason != _po.TABLE_RESTRICTED, {"reason": reason})
+
+
 # --- where Fabric is --------------------------------------------------------------------------------------------
 
 def fabric_root(platform: str = sys.platform, env: Optional[Dict[str, str]] = None) -> Path:
@@ -233,8 +247,7 @@ def post_mcp(origin: str, body: Dict[str, Any], bearer: str, session: Optional[s
         raw = resp.read(4 * 1024 * 1024)
         got = {k.lower(): v for k, v in resp.getheaders()}
     except _po.ListenerRefused as exc:
-        raise HubError("foreign-user", "The hub's port is not held by this OS account's process (%s); nothing was sent."
-                       % (exc.owner.kind if exc.owner else exc.code), True) from None
+        raise listener_refusal(exc) from None
     except (OSError, http.client.HTTPException) as exc:
         raise HubError("hub-unavailable", "Fabric's hub did not answer (%s)." % exc.__class__.__name__, True) from None
     finally:

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

@@ -825,7 +825,7 @@ class McpToolServer:
             gated = self._gate_action(action, "fabric.job.get", {"id": job_id, "inputResponses": {key: value}}, None, None,
                                       headers, tier, meta, caller, mandate)
             if not gated["ok"]:
-                return gated
+                return dict(gated, capability=private.get("capability"))  # the one read names the fault (FAA-186)
             records[key] = gated["record"]
         return {"ok": True, "records": records}
 
@@ -933,7 +933,7 @@ class McpToolServer:
                 if not inputs["ok"] and "invalid" in inputs:
                     return self._error(rid, -32602, inputs["invalid"])
                 if not inputs["ok"]:
-                    stored = self.jobs.private(str(arguments.get("id", ""))).get("capability")
+                    stored = inputs.get("capability")  # read once, by _gate_inputs (FAA-186)
                     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)}