@passioncode-ai/passioncode 0.2.39 → 0.2.40

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

@@ -74,7 +74,9 @@ def login_path(path):
 
 def safe_path(path):
     return (isinstance(path, str) and path.startswith('/') and not path.startswith('//')
-            and len(path) <= 2048 and not re.search(r'[\\\x00-\x1f\x7f]', path))
+            and len(path) <= 2048 and not re.search(r'[\\\x00-\x1f\x7f]', path)
+            # JavaScript's whitespace (\s), which the contract's parseDashboardsLink refuses in a page (DEC-0123)
+            and not re.search('[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]', path))
 
 
 def check(data):
@@ -87,11 +89,11 @@ def check(data):
     require(not re.search(r'[\\\x00-\x20\x7f]', native + http), 'unsafe_url')
     deep, plain = urlsplit(native), urlsplit(http)
     require(deep.scheme == 'fabric-dashboards' and not deep.username and not deep.password and not deep.port and not deep.fragment, 'invalid_deep_link')
-    query = parse_qs(deep.query, keep_blank_values=True, strict_parsing=True)
-    if deep.netloc == 'service':
-        require(deep.path in ('/' + service, '/' + service + '/') and set(query) <= {'path'}, 'wrong_service_or_parameter')
-    else:
-        require(deep.netloc == 'open' and deep.path in ('', '/') and query.get('service') == [service] and set(query) <= {'service', 'path'}, 'invalid_legacy_link')
+    # An empty query is no fields: Python 3.9's strict parse_qs raises on '' where 3.11 and later answer {}.
+    query = parse_qs(deep.query, keep_blank_values=True, strict_parsing=True) if deep.query else {}
+    # DEC-0123 PL-1: only the service form; the legacy open?service= link is refused (FAC-SEM-143, since 0.51.0).
+    require(deep.netloc == 'service', 'not_service_link')
+    require(deep.path in ('/' + service, '/' + service + '/') and set(query) <= {'path'}, 'wrong_service_or_parameter')
     require('path' not in query or len(query['path']) == 1, 'duplicate_path')
     page = query.get('path', [None])[0]
     require(page is None or safe_path(page), 'unsafe_path')

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

@@ -82,6 +82,8 @@ from check_service_rules import same_repository  # noqa: E402,F401 - moved (FAA-
 from check_service_rules import merge_headers, session_cookie  # noqa: E402,F401 - FAA-115
 from check_service_rules import well_known_actions_verdict, action_tools_verdict, actions_declared_verdict  # noqa: E402 - DEC-0121
 from check_service_rules import opens_in_host_verdict, service_checkout  # noqa: E402 - FAA-118
+from check_service_rules import well_known_a2a_verdict, a2a_card_verdict  # noqa: E402 - DEC-0122
+import fabric_a2a as fa2  # noqa: E402 - DEC-0122
 
 
 class _PinnedHTTPS(http.client.HTTPSConnection):
@@ -275,6 +277,8 @@ class Probe:
                      "%d connection(s), %d named in degraded[]" % (len(view["connections"]), failing))
         # DEC-0121, FAC-SEM-142: every button's agent twin, declared; no declaration is NOT_RUN (D10).
         self.add("well-known.actions", *well_known_actions_verdict(wk))
+        # DEC-0122: where the public Agent Card is; no member is NOT_RUN.
+        self.add("well-known.a2a", *well_known_a2a_verdict(wk))
         self.configuration_rule()
         svc = wk.get("service") or {}
         answered = "%s.%s" % (svc.get("id"), svc.get("instance"))
@@ -422,6 +426,23 @@ class Probe:
         self.add("usage.report", "FAIL" if problems else "PASS",
                  "; ".join(problems[:5]) if problems else "%d day(s), unknown cost kept null" % len(days or []))
 
+    # A2A (DEC-0122) ---------------------------------------------------------------
+    def a2a_rules(self) -> None:
+        """`a2a.card`: the public card read with no Authorization header and never the descriptor's token (D5); its
+        interfaces are never called. The verdict is check_service_rules.a2a_card_verdict."""
+        view = fa2.a2a_view(self.wk)
+        status, body, error = 0, b"", None
+        if view["valid"]:
+            # Non-ASCII and control characters the schema's path admits are sent percent-encoded.
+            target = urllib.parse.quote(view["path"], safe="".join(chr(c) for c in range(0x21, 0x7F)))
+            try:
+                status, _, body = self.request("GET", target)  # Host only: no token header is added here
+            except (OSError, ssl.SSLError, http.client.HTTPException) as exc:
+                error = str(exc) or type(exc).__name__
+        header, _ = fs.token_header(self.d.get("auth"), "")
+        self.add("a2a.card", *a2a_card_verdict(self.wk, status, body, remote=self.remote, origin=str(self.d.get("origin") or ""),
+                                               descriptor_header=header, error=error))
+
     # dashboard (fabric-dashboard/0.1, DEC-0036) --------------------------------
     def dashboard_rules(self) -> None:
         wk = self.wk or {}
@@ -851,6 +872,7 @@ class Probe:
             self.network_rules()
             self.auth_rules()
             self.usage_rules()
+            self.a2a_rules()
             self.dashboard_rules()
             self.dashboard_page_rules()
             self.login_rules()

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

@@ -1,7 +1,7 @@
 """The probe's rules that read one thing and need no running service (FAA-65): a plist's marker and priority, the
 network guard's verdict, the board responder's fixture conversation, a session cookie's lifetime, a usage report,
 whether two repository URLs name one repository, a service's actions declaration (DEC-0121) and whether its checkout
-opens its pages in a browser (FAA-118). ``check_service.py`` runs them against a live service.
+opens its pages in a browser (FAA-118), and its A2A member and public Agent Card (DEC-0122). ``check_service.py`` runs them against a live service.
 Standard library only, Python 3.9+."""
 from __future__ import annotations
 
@@ -19,6 +19,7 @@ from typing import Any, Dict, Iterable, List, Optional, Tuple
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402 - beside this file
 import fabric_actions as fa  # noqa: E402 - beside this file (DEC-0121)
+import fabric_a2a as fa2  # noqa: E402 - beside this file (DEC-0122)
 
 
 def plist_problems(plist: dict, label: object, token: object = None) -> list:
@@ -369,6 +370,51 @@ def actions_declared_verdict(wk: Any) -> Tuple[str, str]:
     return "PASS", "the dashboard declares %d action(s) with their tools (DEC-0121 AP-1)" % len(view["actions"])
 
 
+
+# A2A (DEC-0122; decisions D4 to D6 of the 0.51.0 brief) -------------------------------------------------------------
+def well_known_a2a_verdict(wk: Any) -> Tuple[str, str]:
+    """`well-known.a2a`: a present `surfaces.a2a` is the schema's (`{path, protocolVersion: "1.0"}`, nothing else). No
+    member is NOT_RUN: the member is a SHOULD for a service that serves a card, and nothing says this one does."""
+    view = fa2.a2a_view(wk)
+    if not view["declared"]:
+        return "NOT_RUN", "no surfaces.a2a: the service names no A2A Agent Card (DEC-0122)"
+    if not view["valid"]:
+        return "FAIL", "; ".join("%s %s: %s" % (f["instancePath"], f["keyword"], f["message"]) for f in view["findings"][:5])
+    return "PASS", "the public Agent Card at %s, A2A %s" % (view["path"], view["protocolVersion"])
+
+
+def a2a_card_verdict(wk: Any, status: int, body: bytes, *, remote: bool, origin: str, descriptor_header: str,
+                     error: Optional[str] = None) -> Tuple[str, str]:
+    """`a2a.card`: the public card, fetched at `surfaces.a2a.path` with no Authorization header and no descriptor
+    token (D5; the caller sends none). On a local placement it answers 200 with a JSON card; on a remote one 401 or
+    403 is a card that is not open, NOT_RUN, never a failure (DEC-0122 item 2: a host and a probe never report a
+    refusal as nonconformance). A card read is judged by fabric_a2a.agent_card_findings (D5, D6). The card's interfaces
+    are never called."""
+    view = fa2.a2a_view(wk)
+    if not view["declared"]:
+        return "NOT_RUN", "no surfaces.a2a: no card to read"
+    if not view["valid"]:
+        return "NOT_RUN", "surfaces.a2a is not readable (well-known.a2a): a host does not know where the card is"
+    where = "%s without the token" % view["path"]
+    if error is not None:
+        return "FAIL", "no answer at %s: %s" % (where, error)
+    if remote and status in (401, 403):
+        return "NOT_RUN", ("HTTP %d at %s: a card that is not open, gated by the service's own credentials or an "
+                           "identity proxy; a refusal is not nonconformance (DEC-0122 item 2)" % (status, where))
+    if status != 200:
+        return "FAIL", ("HTTP %d at %s: %s" % (status, where, "the public card answers 200" if remote else
+                        "on a local placement the public card answers without authentication (DEC-0122 item 2)"))
+    try:
+        card = json.loads(body)
+    except (ValueError, RecursionError):
+        return "FAIL", "the answer at %s is not JSON" % where
+    findings = fa2.agent_card_findings(card, origin=origin or None, remote=remote, descriptor_header=descriptor_header)
+    if findings:
+        return "FAIL", "; ".join("%s: %s" % (f["code"], f["message"]) for f in findings[:5]) + (
+            " (%d more)" % (len(findings) - 5) if len(findings) > 5 else "")
+    return "PASS", "%d interface(s), A2A %s, read at %s; no process member, secret or descriptor token scheme" % (
+        len(card["supportedInterfaces"]), fa2.A2A_PROTOCOL_VERSION, where)
+
 # dashboard.opens-in-host (FAA-118; the operator rule of 2026-10-24; decision D13) ----------------------------------
 # A service's own pages open only through Fabric Dashboards: the `open_link` of the fabric-dashboards MCP `link` tool,
 # opened with the host's `open` and `fallback=never`; a browser only on a confirmed `not_installed` host. The rule reads

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-a2a.mjs

@@ -0,0 +1,170 @@
+// The reading side of an A2A Agent Card (DEC-0122): the well-known document's surfaces.a2a member, read as the contract's
+// schema reads it (a2aSurfaceFindings, a2aView; a2aSurface builds one), and what a public card must not carry
+// (agentCardFindings): no member about the running process, no secret, no securitySchemes entry naming the descriptor's
+// token header, every Fabric extension required: false (or absent, which A2A reads as false), and interface URLs where the placement puts them. Serving a
+// card, the A2A binding and a client are not here (FAA-10).
+// Part of the Node service kit (layer L3); the twin of fabric_a2a.py. Node 20+, no dependency.
+import { ServiceError } from './fabric-base.mjs';
+import { isObject } from './fabric-jsvalue.mjs';
+import { secretValue } from './fabric-secrets.mjs';
+
+/** A2A 1.0 section 8.2: where a peer looks for the public card. */
+export const A2A_SURFACE_PATH = '/.well-known/agent-card.json';
+/** The A2A version the contract pins (the A2A peer profile); surfaces.a2a.protocolVersion is this constant. */
+export const A2A_PROTOCOL_VERSION = '1.0';
+/** The contract's extension namespace (decision D6): an extension whose uri starts here is a Fabric fact. */
+export const FABRIC_EXTENSION_PREFIX = 'https://fabric.passioncode.ai/';
+/** The well-known document's members about the running process, which a public card never carries (DEC-0122 item 2). */
+export const PROCESS_MEMBERS = Object.freeze(['build', 'process', 'pid', 'status', 'summary', 'degraded']);
+export const MAX_PATH = 2048; // service-common.schema.json originPath maxLength, counted in code points as ajv counts it
+
+// The schema's originPath pattern, under the `u` flag as ajv compiles it.
+const ORIGIN_PATH = /^\/(?!\/)[^\s]*$/u;
+const HTTPS = /^https:\/\//i;
+const MEMBERS = ['path', 'protocolVersion'];
+
+const pointer = (...parts) => parts.map((p) => '/' + String(p).replaceAll('~', '~0').replaceAll('/', '~1')).join('');
+const asciiLower = (text) => text.replace(/[A-Z]/g, (c) => c.toLowerCase());
+const finding = (instancePath, keyword, message) => ({ instancePath, keyword, message });
+
+/** surfaces.a2a against service-well-known.schema.json at the pin, in ajv's order: each finding's instancePath and keyword
+ * are the schema error's (test/fixtures/contract/a2a-vectors.json), with a sentence. */
+export function a2aSurfaceFindings(value, base = '/surfaces/a2a') {
+  if (!isObject(value)) return [finding(base, 'type', 'surfaces.a2a is an object {path, protocolVersion}')];
+  const found = MEMBERS.filter((k) => !Object.hasOwn(value, k)).map((k) => finding(base, 'required', `surfaces.a2a has no ${k}`));
+  for (const k of Object.keys(value)) {
+    if (!MEMBERS.includes(k)) found.push(finding(base, 'additionalProperties', `surfaces.a2a has no member ${k}: the card names its interfaces, bindings and security schemes (DEC-0122)`));
+  }
+  if (Object.hasOwn(value, 'path')) {
+    const path = value.path;
+    if (typeof path !== 'string') found.push(finding(`${base}/path`, 'type', 'surfaces.a2a.path is a string'));
+    else {
+      if ([...path].length > MAX_PATH) found.push(finding(`${base}/path`, 'maxLength', `surfaces.a2a.path is longer than ${MAX_PATH} characters`));
+      if (!ORIGIN_PATH.test(path)) found.push(finding(`${base}/path`, 'pattern', 'surfaces.a2a.path is not a path on the service origin (one leading /, no whitespace)'));
+    }
+  }
+  if (Object.hasOwn(value, 'protocolVersion') && value.protocolVersion !== A2A_PROTOCOL_VERSION) {
+    found.push(finding(`${base}/protocolVersion`, 'const', `surfaces.a2a.protocolVersion is ${A2A_PROTOCOL_VERSION}, the A2A version the contract pins`));
+  }
+  return found;
+}
+
+/** The findings of a2aSurfaceFindings as sentences; empty when the member is valid. */
+export const a2aSurfaceProblems = (value) => a2aSurfaceFindings(value).map((f) => f.message);
+
+/** The surfaces.a2a member for a service that serves its public card at `path` (DEC-0122 item 1). */
+export function a2aSurface(path = A2A_SURFACE_PATH) {
+  const surface = { path, protocolVersion: A2A_PROTOCOL_VERSION };
+  const problems = a2aSurfaceProblems(surface);
+  if (problems.length) throw new ServiceError(`surfaces.a2a: ${problems.join('; ')}.`);
+  return surface;
+}
+
+/** What a host reads of a well-known document's A2A member; never throws. `declared` is whether surfaces.a2a is present,
+ * `valid` whether it is the schema's, `path` the card's path when it is, `findings` the schema's. */
+export function a2aView(wk) {
+  const surfaces = isObject(wk) ? wk.surfaces : undefined;
+  if (!isObject(surfaces) || !Object.hasOwn(surfaces, 'a2a')) return { declared: false, valid: false, path: null, protocolVersion: null, findings: [] };
+  const findings = a2aSurfaceFindings(surfaces.a2a);
+  const valid = findings.length === 0;
+  return { declared: true, valid, path: valid ? surfaces.a2a.path : null, protocolVersion: valid ? A2A_PROTOCOL_VERSION : null, findings };
+}
+
+const card = (code, instancePath, message) => ({ code, instancePath, message });
+
+// Every string the card holds that is shaped like a credential, by its place; walked without recursion, in the order
+// JavaScript lists keys.
+function secrets(root) {
+  const found = [];
+  const stack = [[root, '']];
+  while (stack.length) {
+    const [node, path] = stack.pop();
+    if (typeof node === 'string') {
+      if (secretValue(node)) found.push(card('secret', path, `${path || 'the card'} holds a value shaped like a credential: a public card carries no secret (DEC-0122 item 2)`));
+    } else if (Array.isArray(node)) {
+      for (let i = node.length - 1; i >= 0; i -= 1) stack.push([node[i], path + pointer(i)]);
+    } else if (isObject(node)) {
+      const keys = Object.keys(node);
+      for (let i = keys.length - 1; i >= 0; i -= 1) stack.push([node[keys[i]], path + pointer(keys[i])]);
+    }
+  }
+  return found;
+}
+
+// D5: a securitySchemes entry that is an API key in the descriptor's own header. With Authorization (the default) the
+// card cannot show the token, so nothing is reported.
+function descriptorSchemes(root, header) {
+  const schemes = root.securitySchemes;
+  if (!isObject(schemes) || !header || asciiLower(header) === 'authorization') return [];
+  const found = [];
+  for (const name of Object.keys(schemes)) {
+    const scheme = schemes[name];
+    if (!isObject(scheme)) continue;
+    let location;
+    let named;
+    if (isObject(scheme.apiKeySecurityScheme)) ({ location, name: named } = scheme.apiKeySecurityScheme); // A2A 1.0
+    else if (scheme.type === 'apiKey') ({ in: location, name: named } = scheme); // the OpenAPI shape of A2A before 1.0
+    else continue;
+    if (location === 'header' && typeof named === 'string' && asciiLower(named) === asciiLower(header)) {
+      found.push(card('descriptor-token-scheme', pointer('securitySchemes', name), `securitySchemes.${name} is an API key in ${header}, the descriptor's token header: an A2A interface never takes the descriptor's token (DEC-0122 item 3)`));
+    }
+  }
+  return found;
+}
+
+// D6: an extension under the contract's namespace is not required (A2A 1.0 section 4.4.4): `required` false or absent,
+// which A2A reads as false (a protobuf-written card drops a false default); true or a non-boolean is a finding.
+function fabricExtensions(root) {
+  const extensions = isObject(root.capabilities) ? root.capabilities.extensions : undefined;
+  if (!Array.isArray(extensions)) return [];
+  const found = [];
+  extensions.forEach((extension, i) => {
+    const uri = isObject(extension) ? extension.uri : undefined;
+    if (typeof uri !== 'string' || asciiLower(uri.slice(0, FABRIC_EXTENSION_PREFIX.length)) !== FABRIC_EXTENSION_PREFIX) return;
+    if (Object.hasOwn(extension, 'required') && extension.required !== false) {
+      found.push(card('fabric-extension-required', pointer('capabilities', 'extensions', i), `the Fabric extension at capabilities.extensions[${i}] is required, so a peer that does not know it cannot call; it carries required: false (DEC-0122 item 4)`));
+    }
+  });
+  return found;
+}
+
+// Where the card's interfaces are (DEC-0122 item 2): on a local placement on the service's loopback origin as written, on
+// a remote one https; every one A2A 1.0.
+function interfaces(root, origin, remote) {
+  const list = root.supportedInterfaces;
+  if (!Array.isArray(list) || list.length === 0) return [card('interfaces-missing', '/supportedInterfaces', "the card names no supportedInterfaces: A2A 1.0 lists a card's interfaces there")];
+  const found = [];
+  list.forEach((entry, i) => {
+    const place = pointer('supportedInterfaces', i);
+    const url = isObject(entry) ? entry.url : undefined;
+    if (typeof url !== 'string') {
+      found.push(card('interface-shape', place, `supportedInterfaces[${i}] is not an interface with a url`));
+      return;
+    }
+    if (remote) {
+      if (!HTTPS.test(url)) found.push(card('interface-scheme', `${place}/url`, `supportedInterfaces[${i}].url is not https: a loopback or plain-http interface is admitted on a local placement only`));
+    } else if (origin && !(url === origin || url.startsWith(`${origin}/`))) {
+      found.push(card('interface-origin', `${place}/url`, `supportedInterfaces[${i}].url is not on the service origin ${origin}, where a peer on this computer reaches it`));
+    }
+    if (entry.protocolVersion !== A2A_PROTOCOL_VERSION) {
+      found.push(card('interface-version', `${place}/protocolVersion`, `supportedInterfaces[${i}] does not expose A2A ${A2A_PROTOCOL_VERSION}, the version surfaces.a2a names`));
+    }
+  });
+  return found;
+}
+
+/** What a public Agent Card must not carry or say (DEC-0122 items 2 to 4; decisions D5, D6), each finding
+ * {code, instancePath, message} naming the place and never the value. `origin` is the service origin the card was read
+ * on (its interfaces' place on a local placement; omitted, the place is not judged), `remote` the placement,
+ * `descriptorHeader` the descriptor's auth.header (default Authorization). It reads the card only: whether an interface
+ * accepts the token cannot be seen without sending it, which DEC-0122 forbids. */
+export function agentCardFindings(value, { origin = null, remote = false, descriptorHeader = 'Authorization' } = {}) {
+  if (!isObject(value)) return [card('card-shape', '', 'the card is not a JSON object')];
+  const found = PROCESS_MEMBERS.filter((k) => Object.hasOwn(value, k))
+    .map((k) => card('process-member', pointer(k), `the card carries ${k}, a member about the running process: a public card carries none (DEC-0122 item 2)`));
+  found.push(...secrets(value));
+  found.push(...descriptorSchemes(value, typeof descriptorHeader === 'string' ? descriptorHeader : ''));
+  found.push(...fabricExtensions(value));
+  found.push(...interfaces(value, origin, remote));
+  return found;
+}

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-actions.mjs

@@ -13,12 +13,15 @@
 //   refused when decision.schema.json would refuse it.
 // - actionCaller(tier, authenticated): the caller a service records (AP-2): the identity it authenticated, else
 //   local:T0 / local:T1 for a caller its local floor authenticated, never a name the call carries.
+// - DEC-0125: actionDecision reads a call's mandate (_meta.mandate) through fabric-mandate.mjs's mandateCovers when the
+//   call carries no decision.
 //
 // The kit has no JSON Schema validator: the two shapes are written here from the schemas, lengths in code points and
 // patterns over the whole string, as the contract's validator reads them. Members are an object's own members (a JSON
 // text has no other kind; an inherited member is not read). Never throws on what it reads. Node 20+, no dependency.
 import { ServiceError } from './fabric-base.mjs';
 import { isObject, jsonEqual } from './fabric-jsvalue.mjs';
+import { mandateCovers } from './fabric-mandate.mjs'; // DEC-0125
 import { formatRfc3339, parseRfc3339Ms } from './fabric-time.mjs';
 
 export const ACTIONS_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/actions/0.1';
@@ -113,8 +116,12 @@ const refuse = (code) => ({ ok: false, code });
  * accepted approval is the approver's; a T2 caller without one gets approval-required with the digest; an accepted
  * elicitation is the operator's; no decision is operator-decision-required; a decision that is not the schema's, is for
  * another action or object, or whose `at` is more than 60 s ahead of `now` or more than 24 h behind it is
- * decision-invalid; otherwise the operator's act, recorded with `caller`. `{fault}` (action-invalid, caller-missing,
- * now-unreadable, digest-missing, url-missing) is the service's own and is never sent to a caller.
+ * decision-invalid; otherwise the operator's act, recorded with `caller`. DEC-0125: a call with no decision that carries
+ * `mandate` (its `_meta.mandate`) is answered as mandateCovers answers, given `self` (the service's own agent id),
+ * `callerAgent` (only an agent id the service authenticated), `effect` (the action's effect class, the service's own
+ * knowledge), `spendUsd` and `project`: covered, {by: 'operator', via: 'mandate', task, chain, caller}. `{fault}`
+ * (action-invalid, caller-missing, now-unreadable, digest-missing, url-missing, effect-missing, self-missing) is the
+ * service's own and is never sent to a caller.
  */
 export function actionDecision(inputs) {
   const field = (key) => member(inputs, key);
@@ -140,6 +147,7 @@ export function actionDecision(inputs) {
   const clock = parseRfc3339Ms(field('now'));
   if (Number.isNaN(clock)) return { fault: 'now-unreadable' };
   const decision = field('decision');
+  if (decision === undefined && field('mandate') !== undefined) return byMandate(field, action, caller);
   if (decision === undefined) return refuse(OPERATOR_DECISION_REQUIRED);
   if (!decisionShape(decision)) return refuse(DECISION_INVALID);
   if (decision.action !== action.id || (has(decision, 'target') && decision.target !== field('target'))) return refuse(DECISION_INVALID);
@@ -148,6 +156,27 @@ export function actionDecision(inputs) {
   return { ok: true, recordAs: { by: 'operator', via: 'relayed-instruction', caller } };
 }
 
+/**
+ * A relayed action's call that carries a mandate and no decision (DEC-0125 MD-3): the mandate decides, as the contract's
+ * byMandate reads it: the service's own `effect` and agent id `self` are required (else a fault), its estimate
+ * `spendUsd` is read when a number and `project` when a string.
+ */
+function byMandate(field, action, caller) {
+  const effect = field('effect');
+  const self = field('self');
+  if (typeof effect !== 'string') return { fault: 'effect-missing' };
+  if (typeof self !== 'string') return { fault: 'self-missing' };
+  const spendUsd = field('spendUsd');
+  const project = field('project');
+  const answer = mandateCovers({
+    mandate: field('mandate'), tier: field('tier'), now: field('now'), self,
+    ...(field('callerAgent') === undefined ? {} : { callerAgent: field('callerAgent') }),
+    call: { capability: action.tool, action: action.id, effect, ...(typeof spendUsd === 'number' ? { spendUsd } : {}), ...(typeof project === 'string' ? { project } : {}) },
+  });
+  if ('recordAs' in answer) return { ok: true, recordAs: { ...answer.recordAs, caller } };
+  return answer; // never `ignored`: the tier was read first, so a T2 call answered approval-required before (MD-5)
+}
+
 /**
  * The host reader of extensions/actions/0.1 (DEC-0121 AP-1), as the contract's actionsView: {declared: false},
  * {declared: true, valid: false, errors} or {declared: true, valid: true, actions}. Never throws.

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-context.mjs

@@ -0,0 +1,151 @@
+// One instance per context (FAA-125, organization row N-11; contract DEC-0082, "One instance per context on a machine"):
+// from a context, `personal` or `org:<orgId>`, the service instance, its folders, descriptor and instance lock.
+// Part of the Node service kit (layer L3, after fabric-descriptor); the twin of fabric_context.py, answer for answer
+// (test/fixtures/kit-context-cases.json). Node built-ins only. The facade fabric-service.mjs does not re-export it.
+// A refusal exits 78 (EX_CONFIG) with nothing created; a second copy for the same context exits 75 as holdSingleInstance does.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { INSTANCE, ServiceError } from './fabric-base.mjs';
+import { descriptorPath } from './fabric-descriptor.mjs';
+import { parseContext } from './fabric-estate.mjs';
+import { InstanceLock, holdSingleInstance } from './fabric-lock.mjs';
+import { atomicWrite, instanceDirs, servicesDir } from './fabric-paths.mjs';
+import { instanceShareGrant } from './fabric-share.mjs';
+import { clockMs } from './fabric-time.mjs';
+
+/** EX_CONFIG: the context is refused; 75 stays "already running" (EXIT_ALREADY_RUNNING). */
+export const EXIT_CONTEXT_REFUSED = 78;
+export const CONTEXT_MARKER = 'fabric-context.json';
+const READABLE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const HASHED_TAIL = /-[0-9a-f]{10}$/;
+const READABLE_MAX = 28;
+const SLUG_MAX = 17;
+/** What each refusal tells the person; the sentence never carries a record or grant value. */
+const REASONS = Object.freeze({
+  'context-invalid': 'the context is neither personal nor org:<orgId> as written',
+  'record-required': "an organization's instance needs this machine's estate record, its machine id and its agentRef",
+  'placement-missing': 'the estate record places no such agent on this machine in that context',
+  'grant-refused': 'its placement names no unrevoked share grant for that context (FAC-SEM-111)',
+  'grant-window': "now is outside its share grant's window",
+  'context-mismatch': `its data folder belongs to another context or instance (${CONTEXT_MARKER})`,
+});
+
+/** A context this machine does not run; `code` is one of REASONS' keys. */
+export class ContextRefused extends ServiceError {
+  constructor(code, detail = '') {
+    super(`${code}: ${detail || REASONS[code]}.`);
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const shown = (context) => (parseContext(context) ? context : 'a context that is neither personal nor org:<orgId>');
+
+/**
+ * The instance name of `context` (brief D15): `personal` is `personalInstance` (`default`); `org:<orgId>` is
+ * `org-<orgId>` when readable (lower-case words joined by single hyphens, at most 28 characters, not ending in a hyphen
+ * and 10 hex digits), else `org-<slug>-<first 10 hex digits of sha256(orgId)>`. Throws ContextRefused.
+ */
+export function contextInstanceName(context, { personalInstance = 'default' } = {}) {
+  const parsed = parseContext(context);
+  if (!parsed) throw new ContextRefused('context-invalid');
+  if (parsed.kind === 'personal') {
+    if (typeof personalInstance !== 'string' || !INSTANCE.test(personalInstance) || personalInstance.startsWith('org-')) {
+      throw new ContextRefused('context-invalid', `the personal instance ${JSON.stringify(personalInstance)} is no instance name outside org-`);
+    }
+    return personalInstance;
+  }
+  const { org } = parsed;
+  if (READABLE.test(org) && org.length <= READABLE_MAX && !HASHED_TAIL.test(org)) return `org-${org}`;
+  const trim = (text) => text.replace(/^-+|-+$/g, '');
+  const slug = trim(trim(org.toLowerCase().replace(/[^a-z0-9]+/g, '-')).slice(0, SLUG_MAX)) || 'x';
+  return `org-${slug}-${crypto.createHash('sha256').update(org, 'utf8').digest('hex').slice(0, 10)}`;
+}
+
+/**
+ * What `context` runs as on this machine; pure (no folder, file or lock). Answers {context, kind, org?, instance, key,
+ * dirs: {data, logs, cache}, descriptorPath, grant?: {id, startsAt?, expiresAt?}}, never the record. `record` is the
+ * verified revision this machine applied; `machineId` and `agentRef` come from whoever installed the instance; `at` is
+ * the clock (a Date or epoch seconds; now when undefined). Throws ContextRefused.
+ */
+export function contextInstance(id, context, {
+  record, machineId, agentRef, at, personalInstance = 'default', servicesDirectory, platform = process.platform,
+} = {}) {
+  const instance = contextInstanceName(context, { personalInstance });
+  const parsed = parseContext(context);
+  const answer = {
+    context, kind: parsed.kind, instance, key: `${id}.${instance}`, dirs: instanceDirs(id, instance, platform),
+    descriptorPath: descriptorPath(id, instance, servicesDirectory ?? servicesDir(platform)),
+  };
+  const havePlace = record !== null && typeof record === 'object' && !Array.isArray(record) && typeof machineId === 'string' && typeof agentRef === 'string';
+  const atMs = at === undefined || at === null ? Date.now() : clockMs(at);
+  if (parsed.kind === 'personal') {
+    if (havePlace) { // brief D20: a personal placement that names a grant is refused; no placement is no refusal
+      const checked = instanceShareGrant(record, machineId, agentRef, context, atMs);
+      if (!checked.ok && checked.code === 'grant-refused') throw new ContextRefused('grant-refused', checked.detail);
+    }
+    return answer;
+  }
+  answer.org = parsed.org;
+  if (!havePlace) throw new ContextRefused('record-required');
+  const checked = instanceShareGrant(record, machineId, agentRef, context, atMs);
+  if (!checked.ok) throw new ContextRefused(checked.code, checked.detail);
+  answer.grant = checked.grant;
+  return answer;
+}
+
+function markerMatches(file, expected) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return error.code === 'ENOENT' ? undefined : false;
+  }
+  let found;
+  try { found = JSON.parse(text); } catch { return false; }
+  return found !== null && typeof found === 'object' && Object.entries(expected).every(([key, value]) => found[key] === value);
+}
+
+/**
+ * Run as `context`'s one instance, before any side effect (brief D17): contextInstance (a refusal writes one sentence
+ * naming the code and exits 78, nothing created); then holdSingleInstance on the instance's data folder (its markers,
+ * its supervised wait, its exit 75); then `<data>/fabric-context.json`: absent, written (0600, atomic); equal, kept;
+ * another context or instance, or unreadable, releases the lock and exits 78 (`context-mismatch`). Resolves to the
+ * instance with its held `lock`; `exit` is injectable as holdSingleInstance has it, and its answer is returned.
+ */
+export async function holdContextInstance(id, context, {
+  record, machineId, agentRef, at, personalInstance = 'default', servicesDirectory, platform = process.platform,
+  waitSeconds, sleep, clock, exit = (code) => process.exit(code), env, argv,
+} = {}) {
+  const refuse = (code) => {
+    process.stderr.write(`${id} will not run for ${shown(context)} (${code}): ${REASONS[code]}.\n`);
+    return exit(EXIT_CONTEXT_REFUSED);
+  };
+  let info;
+  try {
+    info = contextInstance(id, context, { record, machineId, agentRef, at, personalInstance, servicesDirectory, platform });
+  } catch (error) {
+    if (error instanceof ContextRefused) return refuse(error.code);
+    throw error;
+  }
+  const lock = await holdSingleInstance(info.dirs.data, {
+    waitSeconds, exit, ...(sleep ? { sleep } : {}), ...(clock ? { clock } : {}), ...(env === undefined ? {} : { env }), ...(argv === undefined ? {} : { argv }),
+  });
+  if (!(lock instanceof InstanceLock)) return lock; // an injected exit answered 75
+  const expected = { service: id, instance: info.instance, context };
+  const marker = path.join(info.dirs.data, CONTEXT_MARKER);
+  let matches;
+  try {
+    matches = markerMatches(marker, expected);
+    if (matches === undefined) atomicWrite(marker, `${JSON.stringify(expected, null, 1)}\n`, 0o600);
+  } catch (error) {
+    lock.release();
+    throw error;
+  }
+  if (matches === false) {
+    lock.release();
+    return refuse('context-mismatch');
+  }
+  return { ...info, lock };
+}

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-delegation.mjs

@@ -15,6 +15,7 @@ import fs from 'node:fs';
 import net from 'node:net';
 import { hubKeyCertified } from './fabric-estate.mjs';
 import { atomicWrite } from './fabric-paths.mjs'; // the kit's private writer (FAA-85)
+import { effectClosure } from './fabric-mandate.mjs'; // defined once beside the mandate that reads it too (DEC-0125)
 
 export const REFUSAL_CODES = Object.freeze([
   'unauthenticated', 'token-expired', 'wrong-audience', 'scope-not-granted', 'effect-above-ceiling', 'no-grant',
@@ -57,7 +58,10 @@ export const REFUSAL_MESSAGES = Object.freeze({
   'issuer-unavailable': "The estate's published keys cannot be read.",
   'unknown-state': 'The state cannot be established, so the call is refused.',
   // DEC-0121 (AP-2, AP-4): the refusals of an action call; each answers 403.
-  'operator-decision-required': "This action is the operator's decision; ask the operator and call again with it in _meta.decision.",
+  'operator-decision-required': "This action is the operator's decision; ask the operator and call again with it in "
+    + "_meta.decision. A client that cannot set _meta: Fabric's agent.call with call.decision, once the hub forwards it; "
+    + "else this service's own elicitation, where the client shows one; else the action's page handed to the operator as "
+    + "Fabric Dashboards' open_link.",
   'decision-invalid': "The call's decision is not valid for this action, object or time.",
   'human-step-required': "This step is the person's own; hand them the link in error.data.url.",
 });
@@ -201,13 +205,8 @@ function chainOf(act) {
   return chain;
 }
 
-/** `none` is below every class and `draft` below every external one; external classes are not ordered. */
-export function effectClosure(ceiling) {
-  const admitted = new Set(ceiling);
-  if (ceiling.length > 0) admitted.add('none');
-  if (ceiling.some((effect) => effect !== 'none')) admitted.add('draft');
-  return admitted;
-}
+/** `none` is below every class and `draft` below every external one: defined once in fabric-mandate.mjs (DEC-0125). */
+export { effectClosure };
 
 export const effectWithin = (effect, ceiling) => effectClosure(ceiling).has(effect);
 
@@ -511,7 +510,16 @@ export function refusalFromAction(answer) {
 }
 
 /** The DL-19 body: {error: {code, message, data: {detail, ...}}}; never a token or a key. */
-export const refusalError = (refusal) => ({ error: { code: refusal.code, message: REFUSAL_MESSAGES[refusal.code] ?? 'Refused.', data: { detail: refusal.detail, ...(refusal.data ?? {}) } } });
+/** DEC-0125 MD-4: a refusal outside a mandate goes back up the chain; only the leading agent asks the operator. */
+export const OUTSIDE_MANDATE_MESSAGE = 'Outside the operator\'s mandate for this call. Call again within your own mandate if it covers this part; else pass this refusal to the agent that called you. Only the leading agent asks the operator, once, about this part alone, then relays a decision or mandate that covers it: in _meta, or, without _meta, through Fabric\'s agent.call once the hub forwards it, the service\'s elicitation, or the action\'s page as a Fabric Dashboards open_link (DEC-0125 MD-4).';
+
+export function refusalError(refusal) {
+  // the gate's answer keeps no-decision at the top and its outside-mandate part in data.detail; only a string names a part
+  const part = typeof refusal.data?.detail === 'string' ? refusal.data.detail : refusal.detail;
+  const outside = refusal.code === 'operator-decision-required' && typeof part === 'string' && part.startsWith('outside-mandate:');
+  const message = outside ? OUTSIDE_MANDATE_MESSAGE : REFUSAL_MESSAGES[refusal.code] ?? 'Refused.';
+  return { error: { code: refusal.code, message, data: { detail: refusal.detail, ...(refusal.data ?? {}) } } };
+}
 
 /** An MCP tools/call result: the refusal as structuredContent with isError true (DL-19). */
 export function refusalToolResult(refusal, traceparent) {

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-descriptor.mjs

@@ -8,6 +8,7 @@ import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
 import { protocolsFindings } from './fabric-protocols.mjs';
 import { CONNECTIONS_EXTENSION_KEY, connectionsView } from './fabric-connections.mjs';
 import { ACTIONS_EXTENSION_KEY, actionsExtension, actionsExtensionRules } from './fabric-actions.mjs';
+import { a2aSurfaceProblems } from './fabric-a2a.mjs';
 import { ROUTES } from './fabric-usage.mjs';
 
 // The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
@@ -382,9 +383,21 @@ export function configurationProblems(doc) {
 // that performs it and its gate, written under extensions/actions/0.1 by actionsExtension. A declaration FAC-SEM-142
 // finds, passed either way, is refused: not its schema's, an id named twice, a humanStep that disagrees with the gate,
 // or a tool surfaces.mcp.capabilities does not list.
-export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols, actions }) {
+// `a2a` (DEC-0122) is surfaces.a2a, where the service serves its public Agent Card (a2aSurface builds one); passed here
+// or in `surfaces`, never both, and refused when it is not the schema's. A reader pinned before DEC-0122 refuses the
+// member, so a service carries it only once its readers are pinned at or after it.
+export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols, actions, a2a }) {
   if (!STATUSES.includes(status)) throw new ServiceError(`status must be one of ${STATUSES.join(', ')}.`);
   if (!surfaces?.events) throw new ServiceError('surfaces.events is required.');
+  if (a2a !== undefined && a2a !== null) {
+    if (Object.hasOwn(surfaces, 'a2a')) throw new ServiceError('surfaces.a2a: pass it in surfaces or as a2a, not both.');
+    surfaces = { ...surfaces, a2a };
+  }
+  if (Object.hasOwn(surfaces, 'a2a')) {
+    // DEC-0122: a host reads the member by the schema; a service never publishes one it would refuse.
+    const problems = a2aSurfaceProblems(surfaces.a2a);
+    if (problems.length) throw new ServiceError(`surfaces.a2a: ${problems.join('; ')}.`);
+  }
   if (!(build?.commit || build?.digest)) throw new ServiceError('build needs a commit or a digest.');
   const doc = {
     protocol: PROTOCOL,