@passioncode-ai/fabric-agent-adapter 0.72.0 → 0.74.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -1,6 +1,6 @@
 # fabric-service/0.1: wire reference
 
-Pinned to `fabric-agent-contract` commit `eac1a594aa131851f079da8bb7b2149e1951f35f`
+Pinned to `fabric-agent-contract` commit `18f8d48762edc5bfb1433657cbfe1c16196df1a6`
 (`docs/specification/service.md`, DEC-0015; the usage report DEC-0021; Windows and Linux supervision
 DEC-0032 and DEC-0033; the operator channel DEC-0034 and DEC-0035; the embedded dashboard DEC-0036;
 delegation and the operator session's lifetime DEC-0039; the meter's call window DEC-0041; session handoff DEC-0042;
@@ -36,6 +36,7 @@ this page is the working summary. Extension key:
 - Well-known document
 - Events page
 - Login code and the operator session
+- The listener's owner (DEC-0154 HA-2)
 - Semantic rules a host applies
 
 ## Descriptor: written by the installer
@@ -48,9 +49,9 @@ File `<id>.<instance>.json`, mode 0600 (on Windows a protected ACL), atomic.
 | Field | Rule |
 |---|---|
 | `protocol` | `"fabric-service/0.1"` |
-| `id`, `instance` | `^[a-z][a-z0-9-]{1,62}$`, `^[a-z][a-z0-9-]{0,31}$` (default `default`); the pair is unique per machine |
+| `id`, `instance` | `^[a-z][a-z0-9-]{1,62}$`, `^[a-z][a-z0-9-]{0,31}$` (default `default`); the pair is unique within one OS account's services directory (DEC-0154) |
 | `name`, `summary` | ≤ 80 and ≤ 200 characters |
-| `origin` | `http://127.0.0.1:<port>`; the port is a machine-wide claim. Optional for an app's descriptor only (`manager: "person"`, DEC-0069): its live origin and process id are in the app's own liveness file, and a descriptor without an origin claims no port (`FAC-SEM-010`) |
+| `origin` | `http://127.0.0.1:<port>`; the port is a declaration no other descriptor in this account's directory makes (`FAC-SEM-010`), kept free on the computer by HA-1, whose claim the kit does not write yet (FAA-225). Optional for an app's descriptor only (`manager: "person"`, DEC-0069): its live origin and process id are in the app's own liveness file, and a descriptor without an origin claims no port (`FAC-SEM-010`) |
 | `auth` | `tokenFile` (0600; on Windows a protected ACL: owner and every granting entry the current user, SYSTEM or Administrators: service.md *Windows token files*, DEC-0032, DEC-0033); `header` default `Authorization` with `scheme` `Bearer`; any other header carries the raw token with `scheme: "none"` |
 | `lifecycle` | `manager` `launchd` (then `label` and `plist`), `systemd` (then `unit`, a `systemctl --user` unit), `task-scheduler` (then `task`, a per-user Scheduled Task), `node` (Project Observatory's node supervises it as its child, with no supervisor file, DEC-0061), `person` (an app a person installs and starts, then `app`, the installed app, DEC-0069) or `none`; `unit` and `task` are refused beside any other manager (DEC-0032), `label` and `plist` beside any but `launchd` (DEC-0057), `app` beside any but `person`. Both kits and the probe accept all six; both kits write the unit and the task (`systemd_unit`, `task_xml` / `systemdUnit`, `taskXml`). An app's descriptor says it is installed, never that it runs: the probe checks `app` is still there (`descriptor.app-installed`) and reads no well-known document; a reader that finds the app gone treats the descriptor as stale (`app_descriptor_stale` / `appDescriptorStale`), and an app that writes its own descriptor rewrites it only when `app_descriptor_action` / `appDescriptorAction` says `write` |
 | `paths` | `data` (required), `logs[]`, optional `config`, `cache` |
@@ -61,7 +62,7 @@ File `<id>.<instance>.json`, mode 0600 (on Windows a protected ACL), atomic.
 | `runner` | optional `{kind?, credentialKind}` (DEC-0061): `credentialKind` `subscription`, `key`, `platform-metered` or `none`: a kind, never a credential (`FAC-SEM-086` refuses a credential-shaped value here or in `installedBy`); a subscription names its vendor's runner (`claude-code`, `kimi-code`, `codex`) |
 | `peer` | optional `{endpoint, custody, residency, maxDataClass}` (DEC-0061): the service is offered to others. `endpoint` `https://<dns-name>[:<port>][/<path>]`, never a reserved name (`FAC-SEM-085`); `custody` `organization-managed`, `personal` or `processor-hosted` (an organization's cloud a processor runs under a processing agreement, DEC-0099); `residency` 1–32 ISO 3166-1 alpha-2 codes, `EU` admitted, user-assigned codes refused; `maxDataClass` `public` < `internal` < `confidential` < `restricted`. An offer needs `runner` and never runs on a subscription. A host sends a request from anyone but the operator only when `peer_refusal` / `peerRefusal` answers null (`FAC-SEM-088`); usage rows may take `route: "platform-metered"` |
 
-A local descriptor MAY say where a collector on the same machine reads its daily operations digests, under
+A local descriptor MAY say where a collector in the same OS account reads its daily operations digests, under
 `https://fabric.passioncode.ai/agent-contract/extensions/ops-digest/0.1` (`fabric-ops-digest/0.1`, DEC-0153, OD-9,
 FAC-SEM-168): 1 to 8 `{dir, source}`, `dir` a folder inside `paths.data`. A remote descriptor carries none, and the key
 is read nowhere else. The kits know the revision and neither write nor check the declaration yet (FAA-206).
@@ -148,8 +149,9 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
   `https://fabric.passioncode.ai/agent-contract/extensions/channel-agent/0.1` (`channel-agent-standard/1`, DEC-0150,
   FAC-SEM-162 to 165) only for a service with no manifest; one with a manifest declares it under its manifest's
   `provider.extensions` alone (CA-1). A well-known answer lists `channel-agent-standard/1` in its `protocols` only once
-  its readers have re-pinned to this revision of the contract (channel-agent.md). The kits know the revision (`PROTOCOL_REVISIONS`) and do not build or check the
-  declaration yet (FAA-197).
+  its readers have re-pinned to this revision of the contract (channel-agent.md). The kits know the revision (`PROTOCOL_REVISIONS`) and do not build the declaration;
+  `check_service.py` checks it (`channel-agent.declaration`, [interop.md](interop.md#what-the-probe-checks)). Fabric
+  Dashboards' sample service keeps its own copy of the protocol table, which no test here holds equal to the kits'.
 - `surfaces.mcp.auth`: `descriptor` (default), `own` (DEC-0024) or `delegation` (DEC-0039, DL-16):
   the MCP surface takes only the estate's delegation tokens, and the top-level
   `auth.delegation {issuer, jwks}` is then required. With `own` or `delegation` the descriptor's
@@ -204,6 +206,34 @@ The session it starts ends 12 h after its last use, 7 days after sign-in, on log
 descriptor token rotates (DEC-0039); a service may shorten either bound, never lengthen one. An
 ended session answers `401` on the dashboard page.
 
+## The listener's owner (DEC-0154 HA-2)
+
+Loopback is one per computer, not one per OS account. Before a client sends any credential to
+`http://127.0.0.1:<port>` (a descriptor's token, a delegation token, a login code's request, a session cookie, a door's
+token), and before a host calls a local service healthy, it tells the owner of the server end of its own connection
+from the computer's socket table. A listener of another OS account, of root, SYSTEM or a service account, or one whose
+owner cannot be told, is `foreign-user`: nothing is sent and nothing it answers is read as the service's. The order of
+a local service's states is `down`, `foreign-user`, `foreign` (`FAC-SEM-009`), then the well-known `status`; the
+well-known `process.pid` is never proof (`docs/specification/service.md#ha-2` at the pin).
+
+The kit's module is `fabric_peer_owner` / `fabric-peer-owner.mjs` (layer L0, [kit modules](kit-modules.md)): `listener(port)`,
+`server_end(sock)` / `serverEnd(socket)`, `peer`, and a connection checked before a byte is written
+(`CheckedHTTPConnection`; Node `checkedSocket`, `CheckedAgent`). Python reads macOS through `sysctl
+net.inet.tcp.pcblist_n` (calibrated on a connected pair of its own, else `netstat -anv`), Linux through `/proc/net/tcp`
+and `/proc/net/tcp6`, Windows through `GetExtendedTcpTable` and the owner's token SID; Node reads `netstat -anv` and `ps`
+on macOS, the same `/proc` files on Linux, and `netstat -ano` with the owner SID from PowerShell `GetOwnerSid` against `whoami /user` on Windows (SIDs, never names). Fail closed: everything but
+`this-account` refuses, `unknown` included.
+
+Every kit client that sends a credential to loopback checks first: `check_service.py` (rule `listener.owner`, the first that reads the port for
+a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`),
+`fabric_http` / `fabric-http.mjs` for a plain `http://` loopback URL (`HttpError` kind `foreign-user`, never retried),
+`check_dashboard_layout.mjs` before a local login code, and the launchd installers' poll (a listener of another account
+is never a successful install; the systemd and Task Scheduler installers do not poll yet, FAA-253). A running board
+session reports a door another account holds as `board.down` with reason `unreachable` until FAA-252. On macOS the Node
+twin reads the pid from `netstat` and the uid from `ps` a few milliseconds apart, so a pid reused in between would be
+misread; the Python twin's `sysctl` reader takes both from one record. A service's own loopback server refusing another account's peer (HA-3) is FAA-227, and the port
+claim file (HA-1) waits on the contract's CT-228.
+
 ## Semantic rules a host applies
 
 | Code | Rule |

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/surfaces-and-auth.md

@@ -27,8 +27,10 @@
   (`auth.delegation-declared`). The kits verify the tokens: put `delegation_gate` /
   `delegationGate` in front of the tools (see [the delegation reference](delegation.md)).
 - Register it into a client config with the service's own command
-  (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
-  atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
+  (`<tool> mcp-register`), which first establishes that the port's listener is this OS account's (the contract's
+  DEC-0154 HA-2: `fabric_peer_owner.server_end` on a connection of its own, as `check_service.py`'s `listener.owner`
+  does; otherwise `foreign-user` and nothing is written), then writes
+  `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}` atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
   goes in `headers`, never in the URL: every log that records a URL prints its query
   string. An HTTP registration starts nothing per session: every client session talks to the
   one resident service (LC-19). A stdio server, by contrast, is a process per session; keep
@@ -39,7 +41,7 @@
 ## CLI for people and scripts
 
 `<tool> service status|start|stop|restart` (launchctl on the label, then the
-well-known document), `<tool> dashboard` (resolve the exact registered service with the `fabric-dashboards`
+well-known document from this OS account's listener, else `foreign-user`: protocol.md, The listener's owner), `<tool> dashboard` (resolve the exact registered service with the `fabric-dashboards`
 MCP, run `check_dashboard_link.py` on the action, then open its `open_link` with the host's `open` and
 `fallback=never`; never `open <url>`, `open -a Safari`, `xdg-open` or `webbrowser.open`; an installed host that
 failed is reported, never replaced by a browser; only a confirmed `not_installed` host permits an explicit browser
@@ -85,7 +87,7 @@ forbids, so it reads the card only and never calls an interface: an API-key sche
 - Created once with `ensure_token` at first start, after the instance lock.
 - Stored at the descriptor's `auth.tokenFile`, 0600, owner-checked, never a symlink.
 - Compared in constant time (`token_matches`).
-- Rotation is an operator act: write a new file, restart, re-run `mcp-register`.
+- Rotation is an operator act: write a new file, restart, re-run `mcp-register` (which checks the listener's owner again).
 - Same-user processes can read it. The protocol defends against web pages and
   mistakes, not against hostile code running as the operator; say so in SECURITY.md.
 

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

@@ -94,7 +94,24 @@ async function serviceTarget(spec, dir) {
   const header = auth.header || 'Authorization';
   const value = (auth.scheme || 'Bearer') === 'Bearer' ? `Bearer ${token}` : token;
   const remote = d.placement === 'remote';
-  const wkRes = await fetch(`${origin}/.well-known/fabric-service`, { headers: remote && token ? { [header]: value } : {} });
+  // Only an https origin goes through fetch. Every other one, a local origin above all, is asked only on a connection
+  // whose server end is this OS account's process (DEC-0154 HA-2): fabric-http (beside this file in the kit) checks it
+  // before the token is sent, refuses with kind foreign-user, and refuses plain http to another host. The path follows
+  // the URL, never the descriptor's placement (0.74.0 unit reading 7: a "remote" descriptor naming 127.0.0.1 sent its
+  // token unchecked). A copy of this file alone cannot tell the owner, so it sends nothing to such an origin.
+  const viaKit = !/^https:\/\//i.test(origin);
+  let kitRequest = null;
+  if (viaKit) {
+    kitRequest = (await import('./fabric-http.mjs').catch(() => null))?.request;
+    if (!kitRequest) throw new Error('fabric-http.mjs and fabric-peer-owner.mjs are not beside this file: the local listener\'s owner cannot be told, so no token is sent (DEC-0154 HA-2)');
+  }
+  const call = !viaKit
+    ? async (method, url, headers) => { const r = await fetch(url, { method, headers }); return { status: r.status, ok: r.ok, json: () => r.json() }; }
+    : async (method, url, headers) => {
+      const r = await kitRequest(method, url, { headers, retries: 0, deadlineS: 10 });
+      return { status: r.status, ok: r.status >= 200 && r.status < 300, json: async () => r.json() };
+    };
+  const wkRes = await call('GET', `${origin}/.well-known/fabric-service`, remote && token ? { [header]: value } : {});
   if (!wkRes.ok) throw new Error(`well-known document answered HTTP ${wkRes.status}`);
   const wk = await wkRes.json();
   const dashboard = wk.surfaces?.dashboard;
@@ -103,7 +120,7 @@ async function serviceTarget(spec, dir) {
   let url = origin + dashboard.path;
   if (dashboard.login) {
     if (!token) throw new Error(`no readable token file for ${id}.${instance}`);
-    const res = await fetch(`${origin}/fabric/v1/login-code`, { method: 'POST', headers: { [header]: value } });
+    const res = await call('POST', `${origin}/fabric/v1/login-code`, { [header]: value });
     if (!res.ok) throw new Error(`login-code answered HTTP ${res.status}`);
     url = origin + (await res.json()).url;
   }

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

@@ -8,6 +8,13 @@
            --board-kit PATH                       (board.responder: the service's own fabric_board.py or fabric-board.mjs)
            --repo PATH                            (dashboard.opens-in-host: the service's checkout)
 
+A local placement is read only when this OS account's process holds its port (DEC-0154 HA-2): `listener.owner`
+comes before every rule that reads the port, from the computer's socket table (fabric_peer_owner). Nothing listening is NOT_RUN (`down`, and
+`well-known.answers` fails as before); another OS account's, root's or SYSTEM's listener, or one whose owner cannot be
+told, FAILs as `foreign-user`, and then no rule reads the port and no credential is sent; one `port.rules` NOT_RUN
+line names the rules not read (as it does when the well-known document gives nothing to read). Every local
+connection, a reconnect included, is checked again before a byte goes out on it.
+
 A remote placement (DEC-0019 — an online agent or dashboard at an https origin) is probed over
 TLS with the certificate verified: the well-known document must refuse a request without the
 token (401 with none of the service's data: an empty body, or an identity proxy's page, DEC-0109), the guards must refuse a foreign Host/Origin and cross-site requests,
@@ -33,6 +40,12 @@ Actions (fabric-actions/0.1, DEC-0121): `well-known.actions` holds a declared ex
 actions with no MCP surface; a remote one there is NOT_RUN, its twin may be on A2A), and `dashboard.actions-declared`
 is NOT_RUN, never FAIL, for a dashboard that declares none (a read-only dashboard cannot declare an empty list).
 
+channel-agent.declaration (DEC-0150, FAC-SEM-162 to 165): extensions/channel-agent/0.1 under provider.extensions of the
+manifest the descriptor names, or, with no manifest, under extensions of the well-known answer (CA-1). FAC-SEM-164's
+obligations on a declaration still read FAIL, and so does a string shaped like a credential in it or in any copy beside
+it; nothing declared, or a declaration read as not declared (a key elsewhere, another version, a form the schema or
+FAC-SEM-163 refuses), is NOT_RUN.
+
 dashboard.opens-in-host (FAA-118, the operator rule of 2026-10-24): the service's checkout (--repo, else the one of
 the descriptor's source.repository that holds its commands, manifest or launchd job) opens the service's pages only
 through Fabric Dashboards. Tracked text files only, within a time budget; a browser opener aimed at its pages outside
@@ -66,6 +79,8 @@ import fabric_service as fs  # noqa: E402
 import fabric_connections as fcn  # noqa: E402
 from check_service_rules import shown_repository  # noqa: E402 - a repository in evidence carries no userinfo or query
 import fabric_interop as fi  # noqa: E402
+import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2: the listener's owner before any credential
+from check_service_rules import ForeignUser, PORT_RULES_UNREAD, listener_owner_verdict  # noqa: E402 - DEC-0154 HA-2
 
 Result = Dict[str, str]
 
@@ -85,6 +100,7 @@ from check_service_rules import well_known_actions_verdict, action_tools_verdict
 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
+import check_service_channel_agent as cac  # noqa: E402 - DEC-0150, FAA-197
 
 
 class _PinnedHTTPS(http.client.HTTPSConnection):
@@ -146,13 +162,16 @@ class Probe:
                 conn = http.client.HTTPSConnection(self.host_name, self.port, context=context, timeout=8)
             base = {"Host": self.netloc}
         else:
-            conn = http.client.HTTPConnection("127.0.0.1", self.port, timeout=5)
+            # DEC-0154 HA-2: every local connection, a reconnect included, is checked before a byte is sent on it.
+            conn = po.CheckedHTTPConnection("127.0.0.1", self.port, timeout=5)
             base = {"Host": "127.0.0.1:%d" % self.port}
         base.update(headers or {})
         try:
             conn.request(method, path, body=body, headers=base)
             resp = conn.getresponse()
             return resp.status, merge_headers(resp.getheaders()), resp.read()
+        except po.ListenerRefused as exc:
+            raise ForeignUser("foreign-user: %s" % exc) from None
         finally:
             conn.close()
 
@@ -161,6 +180,14 @@ class Probe:
         name, value = fs.token_header(self.d.get("auth"), self.token or "")
         return {name: value}
 
+    # the listener's owner (DEC-0154 HA-2) -------------------------------
+    def listener_rule(self) -> bool:
+        """DEC-0154 HA-2, `down` then `foreign-user` then the answer (check_service_rules.listener_owner_verdict). False
+        when the port must not be read (`foreign-user`)."""
+        verdict, evidence = listener_owner_verdict(self.port)
+        self.add("listener.owner", verdict, evidence)
+        return verdict != "FAIL"
+
     # descriptor ------------------------------------------------------------
     def descriptor_rules(self) -> None:
         problems = fs.validate_descriptor(self.d)
@@ -193,7 +220,7 @@ class Probe:
         elif "origin" not in self.d:
             unique = "an app's descriptor names no origin, so it claims no port (FAC-SEM-010)"
         else:
-            unique = "port %d is unique" % self.port
+            unique = "no other descriptor here declares port %d (HA-1's claim on the computer is FAA-225)" % self.port
         self.add("descriptor.port-claim", "FAIL" if clashes else "PASS", "; ".join(clashes) or unique)
         # FAA-198: the repository that links the agent to its project; a new install is refused without it, an installed one
         # is named here (NOT_RUN is no pass) until its owner adds it.
@@ -248,11 +275,18 @@ class Probe:
             return
         try:
             self.wk = json.loads(body)
+            self.wk_bytes = len(body)  # D4 of the 0.73.0 brief: a well-known answer shares a 2 MiB cap
         except ValueError:
             if self.remote:
                 self.add_no_token(no_token, None)
             self.add("well-known.answers", "FAIL", "body is not JSON")
             return
+        if not isinstance(self.wk, dict):
+            self.wk = None
+            if self.remote:
+                self.add_no_token(no_token, None)
+            self.add("well-known.answers", "FAIL", "body is not a JSON object")
+            return
         if self.remote:
             self.add_no_token(no_token, self.wk)
         self.add("well-known.answers", "PASS", "HTTP 200")
@@ -638,6 +672,14 @@ class Probe:
                 self.trace_rule(listing, sent)
         self.events_trace_rule(self.events)
 
+    def channel_agent_rule(self) -> None:
+        """DEC-0150 (FAA-197): the channel agent's declaration, read from the manifest the descriptor names, else from the
+        well-known answer (CA-1); one read as not declared is NOT_RUN with its evidence, never a FAIL (D3), except a string
+        shaped like a credential in it or in a copy the probe reads beside it (CA-5)."""
+        manifest, _, where = self.load_manifest()
+        self.add("channel-agent.declaration", *cac.declaration_verdict(
+            manifest, bool(self.d.get("fabricManifest")), where, self.wk, getattr(self, "wk_bytes", None)))
+
     def configuration_rule(self) -> None:
         """DEC-0046: a well-known `configuration` is {slots, resolved} as the schema types it; absent is NOT_RUN."""
         if not isinstance(self.wk, dict) or "configuration" not in self.wk:
@@ -883,8 +925,16 @@ class Probe:
             return self.results
         if not self.port:
             return self.results
+        if not self.remote and not self.listener_rule():
+            self.add("port.rules", "NOT_RUN", "not read: " + PORT_RULES_UNREAD + ", because the listener is not this OS "
+                     "account's (listener.owner FAIL, DEC-0154 HA-2)")
+            self.lifecycle_rules()
+            return self.results
         self.well_known_rules()
-        if self.wk is not None:
+        if self.wk is None:
+            self.add("port.rules", "NOT_RUN", "not read: " + PORT_RULES_UNREAD + ", because well-known.answers above "
+                     "got no document to read")
+        else:
             self.network_rules()
             self.auth_rules()
             self.usage_rules()
@@ -893,6 +943,7 @@ class Probe:
             self.dashboard_page_rules()
             self.login_rules()
             self.interop_rules()
+            self.channel_agent_rule()
             verdict, evidence = board_responder_verdict(self.wk, self.board_kit)
             self.add("board.responder", verdict, evidence)
         self.lifecycle_rules()