@passioncode-ai/fabric-agent-adapter 0.19.0 → 0.21.0

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

@@ -187,7 +187,11 @@ def runner_check(entry: Dict[str, Any], *, path: Optional[str] = None,
                  run: Callable[..., Any] = subprocess.run) -> Dict[str, Any]:
     """runners.md C2: is the catalogued runner installed, which version answers, and is it signed in. Only a bare
     catalogued binary found on PATH is run, only with the catalogued version argv (and `auth` argv), without a shell,
-    within its timeout (at most 5 s). A catalogue entry outside these rules is refused and nothing runs."""
+    within its timeout (at most 5 s). A catalogue entry outside these rules is refused and nothing runs.
+
+    ``probe`` is the contract's closed probe result for a walk (DEC-0026): ``not-installed`` (no catalogued binary on
+    PATH), ``not-responding`` (the version probe did not answer, failed or did not match the catalogue's pattern),
+    ``not-connected`` (it answers, but the ``auth`` probe says signed out), or None when the runner can serve."""
     kind = entry.get("kind")
     binaries = entry.get("binaries")
     if not isinstance(binaries, list) or not binaries or not all(isinstance(b, str) and _BARE_BINARY.match(b) and ".." not in b for b in binaries):
@@ -201,11 +205,13 @@ def runner_check(entry: Dict[str, Any], *, path: Optional[str] = None,
     if not isinstance(timeout_ms, int) or isinstance(timeout_ms, bool) or not 0 < timeout_ms <= MAX_PROBE_MS:
         raise ProfileError("version.timeoutMs is at most %d" % MAX_PROBE_MS)
     auth_argv = _argv(entry["auth"], "auth") if "auth" in entry else None
-    out: Dict[str, Any] = {"kind": kind, "installed": False, "binary": None, "version": None, "signedIn": None, "problems": []}
+    out: Dict[str, Any] = {"kind": kind, "installed": False, "binary": None, "version": None, "signedIn": None,
+                           "probe": "not-installed", "problems": []}
     binary = next((found for found in (shutil.which(name, path=path) for name in binaries) if found), None)
     if binary is None:
         out["problems"].append("%s is not installed: none of %s is on PATH" % (kind, ", ".join(binaries)))
         return out
+    out["probe"] = "not-responding"
     out.update(installed=True, binary=binary)
 
     def probe(argv: List[str]) -> Optional[Any]:
@@ -224,12 +230,18 @@ def runner_check(entry: Dict[str, Any], *, path: Optional[str] = None,
             out["version"] = match.group(1)
         else:
             out["problems"].append("%s answered, but its version did not match the catalogue's pattern" % kind)
-    if auth_argv is not None:
-        signed = probe(auth_argv)
-        if signed is not None:
-            out["signedIn"] = signed.returncode == 0
-            if not out["signedIn"]:
-                out["problems"].append("%s is installed but not signed in" % kind)
+    signed = probe(auth_argv) if auth_argv is not None else None
+    if signed is not None:
+        out["signedIn"] = signed.returncode == 0
+        if not out["signedIn"]:
+            out["problems"].append("%s is installed but not signed in" % kind)
+    # The walk's order (runners.md): installed, then responding, then connected. The doctor still reports every problem.
+    if out["version"] is None or (auth_argv is not None and signed is None):
+        out["probe"] = "not-responding"
+    elif out["signedIn"] is False:
+        out["probe"] = "not-connected"
+    else:
+        out["probe"] = None
     return out
 
 
@@ -275,3 +287,200 @@ def configuration_summary(doc: Dict[str, Any]) -> List[Dict[str, Any]]:
         first = (resolved.get("models") or [None])[0]
         tiles.append({"label": "Model", "value": " · ".join(x for x in (resolved["modelProfile"], first) if x)})
     return tiles
+
+
+# --- runner routes (DEC-0026, DEC-0029; FAC-SEM-028…034) ----------------------------------------------------------
+# The contract's routeRules (src/route-rules.ts), ported finding for finding: code, path and message.
+
+#: The closed probe results a walk records for a candidate it passed over (runner-route-event.schema.json).
+PROBE_RESULTS = ("not-catalogued", "not-admitted", "not-installed", "not-responding", "not-connected", "no-held-session",
+                 "quota-unknown", "refused", "spawn-failed")
+_MISSING = object()
+
+
+def _field(value: Dict[str, Any], key: str) -> str:
+    """String(value[key]) as JavaScript writes it: `undefined` for a missing key, `null` for null."""
+    found = value.get(key, _MISSING) if isinstance(value, dict) else _MISSING
+    if found is _MISSING:
+        return "undefined"
+    if found is None:
+        return "null"
+    return _js_string(found)
+
+
+def _object_at(value: Any, key: str) -> Dict[str, Any]:
+    found = value.get(key) if isinstance(value, dict) else None
+    return found if isinstance(found, dict) else {}
+
+
+def _ref_key(ref: Any) -> str:
+    if not isinstance(ref, dict):
+        return ""
+    return "%s@%s#%s" % (_field(ref, "id"), _field(ref, "revision"), _field(ref, "contentHash"))
+
+
+def _same_ref(a: Any, b: Any) -> bool:
+    return _ref_key(a) != "" and _ref_key(a) == _ref_key(b)
+
+
+def _candidates(value: Any) -> List[Dict[str, Any]]:
+    return _list(value.get("candidates") if isinstance(value, dict) else None)
+
+
+def _runner_route(value: Dict[str, Any]) -> List[Dict[str, str]]:
+    findings, kinds = [], set()
+    for index, candidate in enumerate(_candidates(value)):
+        kind = _field(candidate, "runnerKind")
+        if kind in kinds:
+            findings.append(_finding("FAC-SEM-028", "/candidates/%d/runnerKind" % index, "runner kind %s appears in the route more than once" % kind))
+        kinds.add(kind)
+        session = _object_at(candidate, "session")
+        if session.get("attach") == "never" and session.get("spawn") == "never":
+            findings.append(_finding("FAC-SEM-029", "/candidates/%d/session" % index, 'candidate %s can never run: attach and spawn are both "never"' % kind))
+    return findings
+
+
+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)}
+    findings = []
+    for index, candidate in enumerate(_candidates(route)):
+        key = _ref_key(candidate.get("provider"))
+        if key not in admitted:
+            findings.append(_finding("FAC-SEM-030", "/route/candidates/%d/provider" % index, "candidate %s names provider %s, which is not a revision admitted for %s"
+                                     % (_field(candidate, "runnerKind"), key, _field(route, "capability"))))
+    if isinstance(value.get("binding"), dict):
+        findings.extend(_binding_agreement(value["binding"], route))
+    if isinstance(value.get("catalogue"), list):
+        findings.extend(_catalogue_agreement(_list(value["catalogue"]), route))
+    return findings
+
+
+def _binding_agreement(binding: Dict[str, Any], route: Dict[str, Any]) -> List[Dict[str, str]]:
+    findings = []
+
+    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):
+        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):
+        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"))
+    if not any(_same_ref(c.get("provider"), binding.get("provider")) for c in _candidates(route)):
+        disagree("provider", "the binding's provider %s is not a candidate of the route" % _ref_key(binding.get("provider")))
+    if "runnerRoute" in binding and not _same_ref(binding["runnerRoute"], route.get("meta")):
+        disagree("runnerRoute", "the binding pins %s, not this route %s" % (_ref_key(binding["runnerRoute"]), _ref_key(route.get("meta"))))
+    return findings
+
+
+def _catalogue_agreement(catalogue: List[Dict[str, Any]], route: Dict[str, Any]) -> List[Dict[str, str]]:
+    by_kind = {_field(entry, "kind"): entry for entry in catalogue}
+    findings = []
+    for index, candidate in enumerate(_candidates(route)):
+        kind = _field(candidate, "runnerKind")
+        entry = by_kind.get(kind)
+        if entry is None:
+            findings.append(_finding("FAC-SEM-033", "/route/candidates/%d/runnerKind" % index, "runner kind %s has no entry in the host's catalogue" % kind))
+            continue
+        if "drive" in candidate and _field(candidate, "drive") not in _object_at(entry, "drives"):
+            findings.append(_finding("FAC-SEM-033", "/route/candidates/%d/drive" % index, "the catalogue entry for %s offers no drive %s" % (kind, _field(candidate, "drive"))))
+    return findings
+
+
+def _index_of(ref: Dict[str, Any]) -> int:
+    index = ref.get("index")
+    if isinstance(index, bool) or not isinstance(index, (int, float)) or not float(index).is_integer():
+        return -1
+    return int(index)
+
+
+def _route_event(value: Dict[str, Any]) -> List[Dict[str, str]]:
+    route = _object_at(value, "route")
+    event = _object_at(value, "event")
+    candidates = _candidates(route)
+    findings: List[Dict[str, str]] = []
+
+    def wrong(path: str, message: str) -> None:
+        findings.append(_finding("FAC-SEM-034", "/event" + path, message))
+
+    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):
+        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):
+        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]]:
+        index = _index_of(ref)
+        candidate = candidates[index] if 0 <= index < len(candidates) else None
+        if (candidate is None or candidate.get("runnerKind", _MISSING) != ref.get("runnerKind", _MISSING)
+                or ("provider" in ref and not _same_ref(candidate.get("provider"), ref["provider"]))):
+            wrong(path, "candidate %s (%s) is not that position of the route" % (_field(ref, "index"), _field(ref, "runnerKind")))
+            return None
+        return candidate
+
+    probes = _list(event.get("probes"))
+    for position, probe in enumerate(probes):
+        candidate = candidate_at(probe, "/probes/%d" % position)
+        if candidate is not None and probe.get("result") == "no-held-session" and _object_at(candidate, "session").get("spawn") != "never":
+            wrong("/probes/%d/result" % position, "%s may spawn, so finding no held session does not pass it over" % _field(probe, "runnerKind"))
+        if candidate is not None and probe.get("result") == "spawn-failed" and _object_at(candidate, "session").get("spawn") != "allowed":
+            wrong("/probes/%d/result" % position, "%s has spawn: never, so it cannot have failed to spawn" % _field(probe, "runnerKind"))
+
+    def expect_probes(count: int) -> None:
+        indexes = [_index_of(p) for p in probes]
+        expected = list(range(max(count, 0)))
+        if indexes != expected:
+            wrong("/probes", "the walk must record candidates %s in order; it records %s"
+                  % (", ".join(map(str, expected)) or "none", ", ".join(map(str, indexes)) or "none"))
+
+    if event.get("kind") == "runner-exhausted":
+        expect_probes(len(candidates))
+        if event.get("answer") == "held" and route.get("exhausted") != "hold":
+            wrong("/answer", "the route does not declare exhausted: hold, so an exhausted walk answers capability-unavailable")
+        return findings
+
+    selected = _object_at(event, "selected")
+    chosen = candidate_at(selected, "/selected")
+    if chosen is not None:
+        session = _object_at(chosen, "session")
+        if selected.get("session") == "attached" and session.get("attach") != "preferred":
+            wrong("/selected/session", "%s has attach: never, so the host cannot attach it" % _field(selected, "runnerKind"))
+        if selected.get("session") == "spawned" and session.get("spawn") != "allowed":
+            wrong("/selected/session", "%s has spawn: never, so the host cannot spawn it" % _field(selected, "runnerKind"))
+        if "drive" in chosen and "drive" in selected and selected["drive"] != chosen["drive"]:
+            wrong("/selected/drive", "the route runs %s through %s, not %s" % (_field(selected, "runnerKind"), _field(chosen, "drive"), _field(selected, "drive")))
+        if event.get("sticky") is True:
+            # A sticky relaunch keeps the conversation's runner and walks nothing above it.
+            if route.get("recovery") == "reprobe":
+                wrong("/sticky", "a route with recovery: reprobe walks from the top at every launch")
+            if "conversation" not in event:
+                wrong("/sticky", "only a conversation can keep its runner")
+            expect_probes(0)
+        else:
+            expect_probes(_index_of(selected))
+
+    if event.get("kind") == "runner-switched":
+        source = _object_at(event, "from")
+        candidate_at(source, "/from")
+        if _index_of(source) == _index_of(selected):
+            wrong("/from", "a switch moves to another candidate")
+        if event.get("reason") == "preferred-available":
+            if route.get("recovery") != "reprobe":
+                wrong("/reason", "only a route with recovery: reprobe moves a conversation back to a preferred runner")
+            if not _index_of(selected) < _index_of(source):
+                wrong("/reason", "preferred-available moves to a higher-preference candidate")
+    return findings
+
+
+def route_problems(kind: str, value: Any) -> Optional[List[Dict[str, str]]]:
+    """The contract's routeRules: findings for a `runner-route` (FAC-SEM-028, 029), a `route-bundle`
+    `{route, admissions, binding?, catalogue?}` (030, 032, 033) or a `route-event` `{route, event}` (034); None for
+    another kind or a value that is not an object."""
+    if not isinstance(value, dict):
+        return None
+    rules = {"runner-route": _runner_route, "route-bundle": _route_bundle, "route-event": _route_event}.get(kind)
+    return rules(value) if rules else None

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

@@ -1364,7 +1364,12 @@ _MAX_ROW_VALUES = 512
 
 
 def _canonical_check(value: Any, at: str = "") -> None:
-    if value is None or isinstance(value, (bool, str)):
+    if value is None or isinstance(value, bool):
+        return
+    if isinstance(value, str):
+        # CT-25 (DEC-0052): Python cannot encode a lone surrogate as UTF-8, so no two languages agree on its bytes.
+        if _SURROGATE.search(value):
+            raise ServiceError("%s: a lone surrogate has no canonical form" % (at or "/"))
         return
     if isinstance(value, int):
         if abs(value) > _SAFE_INTEGER:
@@ -1380,6 +1385,7 @@ def _canonical_check(value: Any, at: str = "") -> None:
         for key, item in value.items():
             if not isinstance(key, str):
                 raise ServiceError("%s: object keys are strings" % (at or "/"))
+            _canonical_check(key, "%s (a key)" % (at or "/"))
             _canonical_check(item, "%s/%s" % (at, key))
         return
     raise ServiceError("%s: %s is not a JSON value" % (at or "/", type(value).__name__))

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.19.0"
+  version: "0.21.0"
   contract-version: "0.1.0"
-  contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
+  contract-commit: "b291bf09e0a9f9fd3c16cf540832cd021203b7d1"
 ---
 
 # 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 `0cacd08b0e95b6abf131eae1206b60792138bc3c` and
+Pin exactly contract `0.1.0` at commit `b291bf09e0a9f9fd3c16cf540832cd021203b7d1` 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