@passioncode-ai/fabric-agent-adapter 0.24.0 → 0.26.0

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

@@ -19,6 +19,7 @@ import shutil
 import subprocess
 from typing import Any, Callable, Dict, List, Optional, Sequence
 
+import fabric_identifiers as _ids
 import fabric_secrets as _secrets
 import fabric_service as _fs
 
@@ -314,9 +315,12 @@ def _object_at(value: Any, key: str) -> Dict[str, Any]:
 
 
 def _ref_key(ref: Any) -> str:
+    """A revision reference compared whole: id, revision and content hash. The id is an identifier, so it enters the key
+    in its normal form (DEC-0076)."""
     if not isinstance(ref, dict):
         return ""
-    return "%s@%s#%s" % (_field(ref, "id"), _field(ref, "revision"), _field(ref, "contentHash"))
+    normal = _ids.normal_identifier(ref.get("id"))
+    return "%s@%s#%s" % (normal if normal is not None else _field(ref, "id"), _field(ref, "revision"), _field(ref, "contentHash"))
 
 
 def _same_ref(a: Any, b: Any) -> bool:
@@ -343,7 +347,7 @@ def _runner_route(value: Dict[str, Any]) -> List[Dict[str, str]]:
 def _route_bundle(value: Dict[str, Any]) -> List[Dict[str, str]]:
     route = _object_at(value, "route")
     admitted = {_ref_key(a.get("provider")) for a in _list(value.get("admissions"))
-                if a.get("state") == "admitted" and a.get("capability", _MISSING) == route.get("capability", _MISSING)}
+                if a.get("state") == "admitted" and _ids.same_identifier(a.get("capability", _MISSING), route.get("capability", _MISSING))}
     findings = []
     for index, candidate in enumerate(_candidates(route)):
         key = _ref_key(candidate.get("provider"))
@@ -363,9 +367,10 @@ def _binding_agreement(binding: Dict[str, Any], route: Dict[str, Any]) -> List[D
     def disagree(path: str, message: str) -> None:
         findings.append(_finding("FAC-SEM-032", "/binding/" + path, message))
 
-    if binding.get("project", _MISSING) != route.get("project", _MISSING):
+    # DEC-0076: project and capability are identifiers, compared by normal form.
+    if not _ids.same_identifier(binding.get("project", _MISSING), route.get("project", _MISSING)):
         disagree("project", "the binding is for %s, the route for %s" % (_field(binding, "project"), _field(route, "project")))
-    if binding.get("capability", _MISSING) != route.get("capability", _MISSING):
+    if not _ids.same_identifier(binding.get("capability", _MISSING), route.get("capability", _MISSING)):
         disagree("capability", "the binding binds %s, the route orders %s" % (_field(binding, "capability"), _field(route, "capability")))
     if binding.get("profileKind") != "local-runner":
         disagree("profileKind", "a runner route serves the local-runner profile, not %s" % _field(binding, "profileKind"))
@@ -408,9 +413,9 @@ def _route_event(value: Dict[str, Any]) -> List[Dict[str, str]]:
 
     if not _same_ref(event.get("route"), route.get("meta")):
         wrong("/route", "the event names route %s, not %s" % (_ref_key(event.get("route")), _ref_key(route.get("meta"))))
-    if event.get("project", _MISSING) != route.get("project", _MISSING):
+    if not _ids.same_identifier(event.get("project", _MISSING), route.get("project", _MISSING)):
         wrong("/project", "the event is for %s, the route for %s" % (_field(event, "project"), _field(route, "project")))
-    if event.get("capability", _MISSING) != route.get("capability", _MISSING):
+    if not _ids.same_identifier(event.get("capability", _MISSING), route.get("capability", _MISSING)):
         wrong("/capability", "the event names %s, the route orders %s" % (_field(event, "capability"), _field(route, "capability")))
 
     def candidate_at(ref: Dict[str, Any], path: str) -> Optional[Dict[str, Any]]:

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

@@ -1305,7 +1305,8 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
                      surfaces: Dict[str, Any], summary: Optional[Sequence[Dict[str, Any]]] = None,
                      update_available: Optional[str] = None, pid: Optional[int] = None,
                      extensions: Optional[Dict[str, Any]] = None,
-                     configuration: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+                     configuration: Optional[Dict[str, Any]] = None,
+                     protocols: Optional[Sequence[str]] = None) -> Dict[str, Any]:
     """The unauthenticated identity answer. `degraded` is always present; ready means empty.
     `configuration` (DEC-0046) says what the operator can configure and what applies now; fabric_profiles builds it.
     `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration
@@ -1339,15 +1340,182 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
         if problems:
             raise ServiceError("configuration: %s." % "; ".join(problems))
         doc["configuration"] = configuration
+    if protocols is not None:
+        # DEC-0067: the revisions this service accepts. The document is closed for a reader pinned before DEC-0067, so
+        # a service lists them only once its hosts are pinned at or after it.
+        problems = protocols_findings(list(protocols))
+        if problems:
+            raise ServiceError("protocols: %s." % "; ".join(f["message"] for f in problems))
+        doc["protocols"] = list(protocols)
     return doc
 
 
+# --- DEC-0067: protocol revisions; DEC-0070: an event's machine-readable data --------------------------------------
+
+#: Each contract protocol's published revisions, oldest first (the contract's `PROTOCOL_REVISIONS`, DEC-0067); a test
+#: holds it equal to the contract's register at the pin.
+PROTOCOL_REVISIONS: Dict[str, Tuple[str, ...]] = {
+    "access-log": ("1",), "approval": ("1",), "activity-summary": ("1",), "estate-record": ("1",), "execution-packet": ("1",),
+    "fabric-activity": ("0.1",), "fabric-dashboard": ("0.1",), "fabric-delegation": ("0.1",), "fabric-device": ("0.1",),
+    "fabric-interop": ("0.1",), "fabric-local-channel": ("0.1",), "fabric-local-runner": ("0.1",),
+    "fabric-operator-channel": ("0.1",), "fabric-package": ("1",), "fabric-project-comms": ("0.1",), "fabric-proposal": ("1",),
+    "fabric-provider": ("0.1",), "fabric-relay": ("0.1",), "fabric-secret-envelope": ("1",), "fabric-service": ("0.1",),
+    "fabric-settings-backup": ("1",), "heartbeat": ("1",), "learning-note": ("1",), "memory": ("0.1",), "pipeline": ("0.1",),
+    "revocation-delta": ("1",), "session-handoff": ("1",), "window-lease": ("1",),
+}
+MAX_PROTOCOLS = 64
+_REVISION = re.compile(r"([a-z][a-z0-9.-]{0,63})/([0-9]{1,4}(?:\.[0-9]{1,4}){0,2})", re.ASCII)
+
+
+def parse_revision(value: Any) -> Optional[Tuple[str, str]]:
+    """`<name>/<revision>` split, or None."""
+    match = _REVISION.fullmatch(value) if isinstance(value, str) else None
+    return (match.group(1), match.group(2)) if match else None
+
+
+def accepted_revisions(name: str, newest: Optional[str] = None) -> List[str]:
+    """The revisions a receiver implementing ``name`` up to ``newest`` accepts: N and, when the register has one, N−1."""
+    known = PROTOCOL_REVISIONS.get(name, ())
+    if not known:
+        return []
+    top = len(known) - 1 if newest is None else (known.index(newest) if newest in known else -1)
+    if top < 0:
+        return []
+    return ["%s/%s" % (name, r) for r in reversed(known[max(0, top - 1):top + 1])]
+
+
+def negotiate_revision(received: Any, accepted: Sequence[Any]) -> Dict[str, Any]:
+    """A receiver's answer to a document naming ``received`` (DEC-0067, the contract's `negotiateRevision`):
+    ``{"ok": True}``; the `schema-unsupported` refusal naming what was received (at most 80 characters) and the accepted
+    revisions of that protocol (all of them when it names none the receiver reads); or ``{"fault":
+    "no-accepted-revisions"}``, the receiver's own, when it accepts no well-formed revision. Revisions compare exactly."""
+    usable: List[str] = []
+    for entry in accepted if isinstance(accepted, (list, tuple)) else []:
+        if parse_revision(entry) and entry not in usable:
+            usable.append(entry)
+    usable = usable[:MAX_PROTOCOLS]
+    if not usable:
+        return {"fault": "no-accepted-revisions"}
+    if isinstance(received, str) and received in usable:
+        return {"ok": True}
+    parsed = parse_revision(received)
+    same = [e for e in usable if parsed and parse_revision(e)[0] == parsed[0]]
+    return {"error": {"code": "schema-unsupported", "message": "this receiver does not read that protocol revision",
+                      "data": {"protocol": received[:80] if isinstance(received, str) else "", "accepted": same or usable}}}
+
+
+def protocols_findings(protocols: Any, prefix: str = "/protocols") -> List[Dict[str, str]]:
+    """FAC-SEM-099 (DEC-0067): 1 to 64 entries, each `<name>/<revision>` once; at most two revisions of one protocol (an
+    unpublished one refused and not counted), and two of a contract protocol are N and N−1, consecutive in the register."""
+    flag = lambda at, message: {"code": "FAC-SEM-099", "instancePath": at, "message": message}  # noqa: E731
+    if not isinstance(protocols, list):
+        return [flag(prefix, "protocols is a list of protocol revisions")]
+    if not 1 <= len(protocols) <= MAX_PROTOCOLS:
+        return [flag(prefix, "protocols lists 1 to %d revisions" % MAX_PROTOCOLS)]
+    findings: List[Dict[str, str]] = []
+    by_name: Dict[str, List[int]] = {}
+    seen: List[str] = []
+    for i, entry in enumerate(protocols):
+        at = "%s/%d" % (prefix, i)
+        parsed = parse_revision(entry)
+        if not parsed:
+            findings.append(flag(at, "a protocol revision is <name>/<revision>, such as fabric-service/0.1"))
+            continue
+        if entry in seen:
+            findings.append(flag(at, "each protocol revision once"))
+            continue
+        seen.append(entry)
+        known = PROTOCOL_REVISIONS.get(parsed[0])
+        if known and parsed[1] not in known:
+            findings.append(flag(at, "%s has no published revision %s" % parsed))
+            continue
+        indices = by_name.setdefault(parsed[0], [])
+        indices.append(known.index(parsed[1]) if known else -1)
+        if len(indices) > 2:
+            findings.append(flag(at, "at most 2 revisions of one protocol: N and N−1"))
+        elif known and len(indices) == 2 and abs(indices[0] - indices[1]) != 1:
+            findings.append(flag(at, "two revisions of one protocol are N and N−1, consecutive in the register"))
+    return findings
+
+
+_SCHEMA_URI = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*:[^\s]+", re.ASCII)
+
+
+def _scalar(value: Any) -> bool:
+    return value is None or isinstance(value, (bool, int, float)) or (isinstance(value, str) and len(value) <= 500)
+
+
+def feed_data_problems(data: Any) -> List[str]:
+    """DEC-0070's `data {schema, value}` as the schema bounds it, then FAC-SEM-101: no string in `value`, at either
+    level, under a credential's name or of a credential's shape (named by its place, never its value)."""
+    import fabric_secrets  # noqa: E402 - beside this file; the contract's detector
+    if not isinstance(data, dict) or set(data) != {"schema", "value"}:
+        return ["data is {schema, value}"]
+    problems: List[str] = []
+    if not (isinstance(data["schema"], str) and _SCHEMA_URI.fullmatch(data["schema"])):
+        problems.append("data.schema is the absolute URI of a payload schema the service publishes")
+    value = data["value"]
+    if not isinstance(value, dict) or len(value) > 32:
+        return problems + ["data.value is an object of at most 32 members"]
+    for key, member in value.items():
+        if _scalar(member):
+            continue
+        if isinstance(member, list) and len(member) <= 32 and all(_scalar(m) for m in member):
+            continue
+        if isinstance(member, dict) and len(member) <= 32 and all(_scalar(m) for m in member.values()):
+            continue
+        problems.append("data.value.%s is a scalar (a string of at most 500 characters), a list of at most 32 scalars or an object of at most 32 scalar members" % key)
+    if problems:
+        return problems
+    for finding in feed_data_findings({"events": [{"data": data}]}):
+        problems.append("FAC-SEM-101: %s %s" % (finding["instancePath"].replace("/events/0", ""), finding["message"]))
+    return problems
+
+
+def _pointer_token(name: str) -> str:
+    return str(name).replace("~", "~0").replace("/", "~1")
+
+
+def feed_data_findings(page: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-101 over an events page (the contract's `feedDataFindings`): a list's items and an object's members sit
+    under the outer name too; a number is a count, never a credential."""
+    import fabric_secrets  # noqa: E402
+    findings: List[Dict[str, str]] = []
+
+    def check(named: bool, member: Any, at: str) -> None:
+        if not isinstance(member, str):
+            return
+        if named:
+            findings.append({"code": "FAC-SEM-101", "instancePath": at, "message": "an event's data puts no string under a credential's name"})
+        elif fabric_secrets.secret_value(member) or fabric_secrets.secret_url(member):
+            findings.append({"code": "FAC-SEM-101", "instancePath": at, "message": "an event's data carries no value shaped like a credential"})
+
+    events = page.get("events") if isinstance(page, dict) else None
+    for i, event in enumerate(events if isinstance(events, list) else []):
+        data = event.get("data") if isinstance(event, dict) else None
+        value = data.get("value") if isinstance(data, dict) else None
+        if not isinstance(value, dict):
+            continue
+        for key, member in value.items():
+            at = "/events/%d/data/value/%s" % (i, _pointer_token(key))
+            named = fabric_secrets.credential_name(key)
+            check(named, member, at)
+            if isinstance(member, list):
+                for j, item in enumerate(member):
+                    check(named, item, "%s/%d" % (at, j))
+            elif isinstance(member, dict):
+                for inner, leaf in member.items():
+                    check(named or fabric_secrets.credential_name(inner), leaf, "%s/%s" % (at, _pointer_token(inner)))
+    return findings
+
+
 # --- events ------------------------------------------------------------------
 
 def make_event(event_id: Any, at: str, kind: str, level: str, text: str, *, subject: Optional[Dict[str, str]] = None,
                link: Optional[str] = None, notify: bool = False, trace_id: Optional[str] = None,
-               span_id: Optional[str] = None) -> Dict[str, Any]:
-    """One activity event: one sentence a person reads, never a machine id.
+               span_id: Optional[str] = None, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """One activity event: one sentence a person reads, never a machine id. `data` (DEC-0070) adds machine-readable
+    fields beside the sentence, `{schema, value}`, never a secret: it is refused here, so no feed carries one.
 
     An event about traced work carries its trace as a pair, `trace_id` and `span_id`
     (fabric-interop/0.1 C3.4 c); fabric_interop.trace_ids(traceparent) gives both."""
@@ -1373,6 +1541,11 @@ def make_event(event_id: Any, at: str, kind: str, level: str, text: str, *, subj
         event["notify"] = True
     if trace_id is not None:
         event["traceId"], event["spanId"] = trace_id, span_id
+    if data is not None:
+        problems = feed_data_problems(data)
+        if problems:
+            raise ServiceError("Event data: %s." % "; ".join(problems))
+        event["data"] = {"schema": data["schema"], "value": data["value"]}
     return event
 
 

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,9 +5,9 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.24.0"
+  version: "0.26.0"
   contract-version: "0.1.0"
-  contract-commit: "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0"
+  contract-commit: "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b"
 ---
 
 # Creating Fabric-compatible agents
@@ -123,7 +123,7 @@ python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/adapt_project.py
 The effect class is declared, never defaulted: ask the author what the agent does outside itself when the request
 does not say. Cost presets are only for a run whose cost varies; their amounts come from the author or measured runs.
 
-Pin exactly contract `0.1.0` at commit `fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0` and
+Pin exactly contract `0.1.0` at commit `a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b` and
 read the pinned guide before implementing protocol details. If this skill is installed
 without its sibling, the scaffolder is absent: create the bundle by hand from the pinned
 contract's `docs/guides/connecting-compatible-agents.md` and mark the structural check

package/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -18,7 +18,7 @@ compatibility: >-
   this plugin; Codex and Kimi Code get the session-start preamble hook on the person's consent.
 metadata:
   author: PassionCode.ai
-  version: "0.24.0"
+  version: "0.26.0"
 ---
 
 # Working with Fabric

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py

@@ -60,7 +60,7 @@ WATCH_MAX_BACKOFF_S = 900
 SESSION_ID = re.compile(r"[A-Za-z0-9._:-]{1,128}")
 LOOPBACK_ORIGIN = re.compile(r"http://127\.0\.0\.1:(\d{1,5})")
 LOCAL_ORIGIN = re.compile(r'"origin": "http://(?:127\.0\.0\.1|localhost)')
-VERSION = "0.24.0"
+VERSION = "0.26.0"
 HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code"}
 # A session Fabric launched. FABRIC_LAUNCHED_SESSION=1 is the marker Fabric is asked to set (need D6); the others are
 # what Fabric already gives a launched session (fabric sessionBundle.ts): only their NAMES are looked at, never a value