@passioncode-ai/fabric-agent-adapter 0.82.0 → 0.83.1

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

@@ -0,0 +1,75 @@
+# Operations digests: a service's own hourly and daily counts
+
+The contract's DEC-0153 ([ops-digest.md at the pin](https://github.com/passioncode-ai/fabric-agent-contract/blob/93e7db164c7829e2783b4b7705c4113bb5201131/docs/specification/ops-digest.md))
+asks every product to count its own operations log and keep two kinds of lines on its own machine: one
+`ops.digest.hourly@1` line for each hour it observed itself running in, an empty one included, and one
+`ops.digest.daily@1` line for each closed UTC day that has hourly lines. No model reads the log; the fold is
+arithmetic. The kit's module is `fabric_ops_digest.py` and its Node twin `fabric-ops-digest.mjs` (FAA-206 part 2).
+
+## Use it
+
+```python
+from fabric_ops_digest import OpsDigest, ops_digest_extension, outcome_of
+
+digests = OpsDigest(paths["data"] / "digests")   # a folder inside the data folder, made 0700
+digests.start()                                   # writes the hour the last run kept, folds missed days
+digests.record("mcp.tools/call", "ok")            # each record of the log, before the log samples it (OD-3)
+digests.record("board.tick", outcome_of(word, {"timeout": "failed", "denied": "unknown"}))
+digests.tick()                                    # once a minute or so: an hour with a tick is written, empty if quiet
+digests.flush()                                   # now and then: writes a closed hour and a closed day
+digests.stop()                                    # at the drain: keeps the open hour for the next run
+```
+
+Node: `new OpsDigest(dir)`, then `start()`, `record(op, outcome)`, `tick()`, `flush()`, `stop()`; `outcomeOf`,
+`opsDigestExtension`.
+
+- **Names (OD-2).** `op` names the operation, never a value of it: a lower-case letter, then letters, digits and `_`
+  in segments joined by `.`, `:`, `/` or `-`, at most 64 characters (`board.tick`, `mcp.tools/list`). A name the
+  grammar refuses, or one shaped like a credential or holding a home folder (FAC-SEM-167), raises `OpsDigestError` at
+  `record`, so no line every reader skips is ever written. The error names the place, never the value.
+- **Outcomes (OD-3).** `ok` and `failed` count as themselves, every other word as `unknown`. A log with its own words
+  maps them with `outcome_of(word, mapping)` and publishes that map in its own documentation; a setup answer (a
+  missing slot, DEC-0149), a refusal or a skip is `unknown`, never `failed`, so an unfinished setup makes no rise.
+- **The overflow name.** A day keeps at most 4095 named operations; the rest are counted under `ops.overflow` (pass
+  `overflow=` to choose another and publish it with the outcome map).
+- **Hours (OD-1).** An hour is written when it closes. Hours the service did not observe (a laptop asleep) are never
+  filled. The hour the service stops in is kept in `kept-hour.json` and written at the next run, compared with the
+  hour before only when that one is the last written; a restart within the same hour resumes it, so no hour has two
+  lines.
+- **Days (OD-5).** Each closed UTC day with hourly lines gets one daily line, at the next run if the service was not
+  running when the day closed (catch-up).
+- **Files (OD-6).** `hourly-YYYY-MM.jsonl` and `daily-YYYY-MM.jsonl`, one JSON line each, files 0600 in a 0700
+  folder. `read_digests(folder, kind)` reads them as a reader does: a bad line skipped, the first line of an hour or a
+  day kept.
+- **Rises (OD-4, OD-8).** A rise is at least 10 failures in an hour and at least twice the hour before's (none counts
+  as one); it is in the hourly line's `risen`. A service that shows findings shows each rise of its newest closed hour
+  with the operation, the failures and the hour before's, never as the cause of a failure.
+- **Nothing but counts (OD-7).** No log line, path, identifier or text ever enters a digest.
+
+## Tell a collector where the daily lines are (OD-9)
+
+A local descriptor that names `paths.data` declares the folder under its `extensions`:
+
+```python
+descriptor["extensions"] = ops_digest_extension([{"dir": "digests", "source": "app"}])
+```
+
+`ops_digest_extension` checks the grammar of `dir` (relative to the data folder, forward slashes, no `.`, `..`, `:`,
+`~` or drive), home folders and credential shapes, and that each `dir` and `source` is named once. The contract's
+FAC-SEM-168 (its caseless fold of `dir` among other things) stays the authority; a remote descriptor never carries the
+key. A collector in the same OS account reads the daily lines and sends them on unchanged; who collects and how is
+Project Observatory's, not the kit's.
+
+## The retro after work
+
+A host that hands sessions the `retro-after-work` obligation counts each ask as one record of the operation
+`retro-after-work` (RW-4): `ok` when it saw a lesson or an `insight/1` line written, `failed` when such a write was
+refused, `unknown` otherwise. working-with-fabric's hooks remind a Claude Code session; the error classes the hooks
+would count wait on FAA-202.
+
+## Checks
+
+`fold_hour` and `fold_day` are the contract's reference folds, run in `test/test_fabric_ops_digest.py` and
+`test/fabric-ops-digest.test.mjs` against the contract's vectors (`test/fixtures/ops-digest/vectors.json`);
+`ops_digest_rules` is FAC-SEM-166 and FAC-SEM-167, run against the contract's positive and semantic fixtures
+(`test/fixtures/ops-digest/rules.json`).

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

@@ -29,7 +29,7 @@ The person writes the descriptive part; `pack` fills in the rest.
 | You write | `pack` writes |
 |---|---|
 | `schema` (`fabric-package/1`), `kind` (`agent` or `skill-set`), `id` (kebab-case, the plugin name), `version` (semver), `publisher` (a name, never a key), `licence` (SPDX) | `agentRef` = `urn:fabric:agent:<publisher>:<id>`, after `publisher` (an agent only; a hand-written one that differs is refused) |
-| an agent: `resultSignal {name, says}`, `evals {suite, receipt {ranAt, suite, passed, failed, skipped?}}`, and as needed `provider`, `service`, `secrets[]` (slots: name and purpose, never a value), `requires`, `costPresets`, `state[]`, `dependencies[]` | `files[]`: every file but `fabric.package.json`, in UTF-16 order, each with `sha256:` and its hex digest |
+| an agent: `resultSignal {name, says}`, `evals {suite, receipt {ranAt, suite, passed, failed, skipped?}}`, and as needed `provider`, `service`, `secrets[]` (slots: name and purpose, never a value), `requires`, `costPresets`, `state[]`, `dependencies[]`; an agent with no `provider` (a consumer agent, DEC-0071) must carry `skills` and `requires` with `requires.mcp`, which the schema refuses it without (FAA-190) | `files[]`: every file but `fabric.package.json`, in UTF-16 order, each with `sha256:` and its hex digest |
 | a skill set: `layer`, `skills` | `digest` |
 
 The evals receipt's `suite` is the SHA-256 of the suite **as packed**. When the suite changes, run it again and write that
@@ -66,8 +66,9 @@ file names needs an ignore line of its own at the new path); a link whose target
 the way to it (an ancestor, or a folder a link above it led into) is removed, so the copy ends; a target that leaves
 that tree or lies in what `.gitignore` keeps out, such as an instance folder in the checkout, is removed, since it is
 the instance or another project. Source the agent shares from outside the tree (a monorepo's common code, linked or
-imported by a relative path) is copied into the agent's tree at the path it is reached by and committed before
-packing. List each link removed and review it: a missing file is not seen by `pack` or `verify`. Leave out dependency
+imported by a relative path) is copied into the agent's tree and committed before packing, and every import that
+reached it by a relative path leaving the tree (`../../common/x`) is changed to the copied path, or the package
+imports a path that is not in it (FAA-190). List each link removed and review it: a missing file is not seen by `pack` or `verify`. Leave out dependency
 folders (`node_modules`, virtual environments, which hold install paths and binaries), what `.gitignore` keeps out as
 instance (the real configuration, an instance folder in the checkout) and the files `pack` refuses by name (a
 credential-free `.npmrc` that `.fabric-source-ignore` names for the check included). `pack` does not read
@@ -76,8 +77,9 @@ and a private `*.jwk` by their names: keep them in the instance.
 
 It refuses to list what must not ship, and names each: a symlink, a special file, `.git`, `__pycache__`, `.DS_Store`,
 `*.pyc`, and files that are credentials by name (`.env` and `.env.*` but `.env.example|sample|template`, `*.pem`, `*.key`,
-`*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `id_rsa`-style keys, `.npmrc`, `.netrc`, `.pypirc`). Remove them or pack a clean
-copy. A member named twice in `fabric.package.json` is refused too. A folder swapped for a link while it is read is refused as a
+`*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `id_rsa`-style keys, `.npmrc`, `.netrc`, `.pypirc`). Pack a clean copy (above);
+remove in place only litter (`__pycache__`, `.DS_Store`, `*.pyc`) and a credential file the instance keeps elsewhere, never
+`.git`: a folder packed after deleting it would carry what `.gitignore` kept out, an instance folder among it (FAA-190). A member named twice in `fabric.package.json` is refused too. A folder swapped for a link while it is read is refused as a
 symlink. The Python kit reads each folder through an open handle, so a swap cannot redirect it. The Node kit has no
 such call: it checks each folder before listing it, after each file it reads and after listing it (FAA-91), and does not
 see a swap made and undone between two of those checks. Pack from a folder only you can write to.

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

@@ -118,7 +118,7 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
   DEC-0122 refuses the member. The kits build it with `a2a_surface()` / `a2aSurface()` (`fabric_a2a`), read it with
   `a2a_view` / `a2aView`, and `build_well_known(a2a=...)` / `buildWellKnown({a2a})` refuse one that is not the
   schema's, passed either way; `agent_card_findings` / `agentCardFindings` say what a public card must not carry
-  ([surfaces and auth](surfaces-and-auth.md#a2a-for-remote-agents)). The kits do not serve a card yet (FAA-10).
+  ([surfaces and auth](surfaces-and-auth.md#a2a-for-remote-agents)). Since 0.83.0 `fabric_a2a_server` / `fabric-a2a-server.mjs` serve the card and the A2A JSON-RPC binding ([A2A](a2a.md), FAA-10).
 - `extensions` MAY carry the embedded dashboard declaration under
   `https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1` (`fabric-dashboard/0.1`,
   ED-9): `minWidth` 360…1280 (required), `appearance` ⊆ `scheme`, `theme`, `themes`, `kit`
@@ -230,23 +230,36 @@ and `/proc/net/tcp6`, Windows through `GetExtendedTcpTable` and the owner's toke
 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.
 
-macOS 27.2 shows an ad-hoc-signed interpreter (a Homebrew Python, measured; a Homebrew Node is ad-hoc-signed too and was not measured) only its own sockets: sysctl lists this
+macOS 27.2 shows an ad-hoc-signed interpreter (a Homebrew Python, measured; a Homebrew Node is ad-hoc-signed too) only its own sockets: sysctl lists this
 process alone and netstat prints nothing. The Python calibration therefore also asks for a child process's listener,
 and a restricted table is `unknown` with a reason beginning `table-restricted` (never another account's): DEC-0155 RT-1
 reads so a netstat that prints nothing or only its header, one that fails or exits non-zero, a table holding no row of
 another uid (sysctl) or of another process (netstat), and a macOS table without the reader's own connection (FAA-312;
 Linux and Windows keep `no-row`). Under it `listener(port)` reads this account's listener as its own only on exactly
 `127.0.0.1` (RT-4). `fabric_peer_owner.py listener <port>` and `fabric-peer-owner.mjs listener <port>` print the kind
-(`--json` the whole owner; FAA-315). A caller that started the
-server itself may vouch with that pid: `lsof -p <pid>` asks the process, which the restriction leaves readable, and a
-listener of this account's pid on the port counts as this account's (`CheckedHTTPConnection(vouch_pid=...)`, Node
-`checkedSocket({vouchPid})`). The launchd installers vouch with their own job's pid; elsewhere a restricted table
-refuses (the probe, the hub client and `fabric_http` included, FAA-272), and Apple's `/usr/bin/python3` sees the
-whole table (FAA-267). A vouch is a weaker proof than the table's: it shows the job's pid listens on exactly `127.0.0.1`
-on the port, not that it accepted this connection. Since FAA-312 every vouch follows DEC-0155 RT-3: a wildcard or `::1`
-listener is never vouched for (`lsof` prints an IPv6-only wildcard as `*:<port>` too), and a reader whose real and
-effective uid differ vouches for nothing. The accepted socket itself (RT-2, libproc or `lsof` of established sockets)
-is not read yet (FAA-292; the repository's `docs/evidence/specs/2026-11-12-faa-292-libproc-decision.md`).
+(`--json` the whole owner; FAA-315).
+
+Under a restricted table the kit asks this account's own processes, which the restriction leaves readable
+(`fabric_socket_proof`, beside `fabric_peer_owner` in every kit install; FAA-292, FAA-272). A server end is this
+account's when one of its processes holds the very socket that accepted the connection (DEC-0155 RT-2, the
+accepted-socket proof; read for up to 0.5 s until the server has called `accept()`), and a listener when one of its
+processes listens on exactly `127.0.0.1:<port>`. Python reads them through libproc (`proc_listpids`, `PROC_PIDLISTFDS`,
+`PROC_PIDFDSOCKETINFO`, Project Observatory's `peer_owner` 1.3.1 reader, calibrated on a pair of its own) and through
+`lsof` when libproc is unavailable; Node through `lsof -nP -a -u <uid> -iTCP:<port> -sTCP:<state> -F pun`, the exact
+address pair and the numeric uid. The proof is "a process of this uid holds the descriptor": a socket another account
+accepted and passed with SCM_RIGHTS to one of this account's processes reads as this account's, which `expect_pid`
+closes; one socket several of its processes hold is proved with no pid (`several-processes`), which skips an
+`expect_pid` check, as a Linux row does. It never answers another account's, root's or nobody's, a set-uid reader gets
+none, and a project that vendors `fabric_peer_owner` alone answers as before. After it, a caller that started the
+server itself may vouch with that pid: `lsof -p <pid>` asks the process, and a listener of this account's pid on the
+port counts as this account's (`CheckedHTTPConnection(vouch_pid=...)`, Node `checkedSocket({vouchPid})`), taken only
+for a connection that reached `127.0.0.1` (one a caller spelled `::1` or `localhost` that reached `::1` is not; FAA-273);
+the launchd installers vouch with their own job's pid. The Node layout probe (`check_dashboard_layout.mjs`) on such a
+host reads this account's dashboard listener through the own-listener proof (`lsof -u`, FAA-272). What neither proves refuses (the probe, the hub client and `fabric_http`
+included, FAA-272), and Apple's `/usr/bin/python3` sees the whole table (FAA-267). A vouch is weaker than RT-2: it
+shows the pid listens on exactly `127.0.0.1` on the port, not that it accepted this connection. Since FAA-312 every
+vouch follows DEC-0155 RT-3: a wildcard or `::1` listener is never vouched for (`lsof` prints an IPv6-only wildcard as
+`*:<port>` too), and a reader whose real and effective uid differ vouches for nothing for its own account.
 
 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`, its

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

@@ -17,7 +17,9 @@ DEC-0019, at the commit this skill pins. This page is the how-to.
 
 It is, when it runs outside the operator's computer and the operator wants it in Fabric beside
 the local services: a hosted dashboard, an agent on a server, a bot's web console. It keeps the
-same objects (well-known document, events feed, login code) at the same paths.
+same objects (well-known document, events feed, login code) at the same paths. An uptime A agent (one that answers
+while the owner's computer is off, creating-fabric-agents' grill) is one from its first release: its keys are the
+platform's secrets, set from Observatory or the person's secret manager, never Observatory's local vault at run time.
 
 ## The descriptor
 
@@ -73,6 +75,13 @@ watch the gate fail.
   time (`tokenMatches`). A service registered from more than one host holds one token per host
   ([Registered from several hosts](#registered-from-several-hosts)).
 - **Session key**: 32 random bytes, a separate secret; rotating it signs every operator out.
+- **The data folder on a disk that does not persist**: set `FABRIC_DATA_HOME` to an absolute folder on the platform's
+  durable volume, and `service_dirs` / `serviceDirs` put the data folder there (`<home>/<id>`, an instance
+  `<home>/<id>.<instance>`); logs and cache stay on the local disk. With no durable volume, keep the data in a
+  durable store (a database, an object store) and nothing of value in the folder. A relative value is refused.
+- **A slow resolver**: `http.server.HTTPServer` resolves its host's FQDN between `bind()` and `listen()`, so on a host
+  with a slow or missing resolver the port is bound and connects time out; serve with the kit's server, never a bare
+  `HTTPServer`.
 - **Codes and sessions**: `MemoryCodeStore`: a restart forgets every outstanding code, so none
   can be replayed, and every session record, so a deploy signs the operator out (DEC-0039: the
   server keeps each session's last use and logout). The host signs in again on the page's `401`.

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

@@ -6,6 +6,7 @@
 - [CLI for people and scripts](#cli-for-people-and-scripts)
 - [A2A for remote agents](#a2a-for-remote-agents)
 - [Behind tailscale serve](#behind-tailscale-serve)
+  - [A groups file at every door](#a-groups-file-at-every-door)
 - [Token](#token)
 - [Dashboard session](#dashboard-session)
 - [Headers every response carries](#headers-every-response-carries)
@@ -124,6 +125,75 @@ A tagged node (a server, not a person) gets no identity header from serve and is
 machine caller uses the estate's delegation tokens instead. The serve listener is an outward surface: watch it like
 the A2A tunnel above.
 
+### A groups file at every door
+
+`fabric_tailnet_identity.py` / `fabric-tailnet-identity.mjs` (FAA-324) are the simpler sibling for a service whose
+every door (its dashboard, its MCP endpoint, its own API) sits behind `tailscale serve` on one loopback listener, with
+access kept in a file the organization writes rather than a generated perimeter and personal keys.
+
+- **The header and where it is believed.** Serve sets `Tailscale-User-Login` and removes any copy a client sent (also
+  the `_` spelling); it sets none for a tagged node or for Funnel traffic, which carries `Tailscale-Funnel-Request`
+  instead ([Tailscale: identity headers](https://tailscale.com/kb/1312/serve)). The module believes the header only
+  when the service listens on a loopback address and the request's peer is loopback; a service bound to `0.0.0.0` or
+  a LAN address, or a request from another peer, is refused, since there the header comes from the network. Another
+  process of the machine can still reach the loopback port: the kit's loopback server refuses other OS accounts
+  (FAA-227), and a listener of serve's own (above) closes the rest where that matters.
+- **The groups file.** JSON the organization writes, at a path the service takes from its own setting (an
+  environment variable or a config key it names), checked against `tailnet-groups.schema.json` beside the module:
+
+  ```json
+  {"schema": "tailnet-groups/1",
+   "about": "Who may open example-agent's doors.",
+   "groups": {"ops": ["ana@example.com", "bo@example.com"], "viewers": ["cy@example.com"]},
+   "rules": [{"group": "ops", "door": "dashboard", "capabilities": "*"},
+             {"group": "ops", "door": "mcp", "capabilities": ["cve.scan", "vitals.read"]},
+             {"group": "ops", "door": "service", "capabilities": "*"},
+             {"group": "viewers", "door": "dashboard", "capabilities": ["vitals"]}]}
+  ```
+
+  A door is `dashboard`, `mcp` or `service`; a capability is the name the service asks for there (a page, a tool, an
+  action), or `"*"` for all of them. The module also reads the agents base's `door-groups/1` file, written once for
+  every service of a machine, for the service it is given (`TailnetIdentity(path, service="example-agent")`, Node
+  `{service}`):
+
+  ```json
+  {"format": "door-groups/1", "version": 3, "generated_at": "2026-11-12T22:00:00Z",
+   "groups": {"ops": {"people": ["ana@example.com"], "doors": {"example-agent": ["dashboard", "mcp"]}},
+              "callers": {"people": ["dee@example.org"], "doors": {"example-agent": ["vitals.read"]}}},
+   "retired": {"old-ops": {"at": "2026-11-01", "why": "merged into ops"}}}
+  ```
+
+  For that service `*` opens every door, `dashboard` the dashboard, `mcp` every MCP tool, and a tool name that tool at
+  the MCP door and at the service's own door; a group with no entry for the service, and a retired group, open
+  nothing, and without a service every door stays closed (`groups-invalid` at `service`). Logins are compared as ASCII names lowercased whole after trimming spaces and
+  tabs, with no other folding; a non-ASCII login (serve RFC 2047-encodes one) is refused as malformed.
+- **Wiring.** Make one `TailnetIdentity(path)` at start and ask it at each door: in Python
+  `decision = identity.decide_request(self, door="mcp", capability=tool)` in an `http.server` handler, then
+  `send_refusal(self, decision)` when `decision["allowed"]` is false; in Node
+  `identity.decideRequest(req, {door, capability})` and `sendRefusal(res, decision)`. Behind the kit's
+  `loopbackServer` gate the request's own server never listened, so pass `bound: gate.address().address` (Python:
+  `bound=` when the handler's server is not the listening one); an unknown bound address is refused. The decision
+  carries `login`, `name` (from `Tailscale-User-Name`, for display only) and `groups`.
+- **Reload and failure.** The file is looked at on every request (one `stat`; `recheck_seconds` / `recheckSeconds`
+  makes it at most that often) and read again when its inode, size, mtime or ctime change, with no restart. While it
+  is missing, unreadable or invalid, every door answers `groups-unreadable` or `groups-invalid`; one line per change
+  goes to the log (stderr by default), naming the field and never the file's content.
+
+| Code | When |
+|---|---|
+| `bind-not-loopback` | the service does not listen on a loopback address, or the address is unknown |
+| `not-loopback` | the request's peer is not loopback: it did not come through the local serve |
+| `groups-unreadable`, `groups-invalid` | the groups file cannot be read, or breaks its schema; every door is shut |
+| `funnel-request` | the request came through Funnel from the public internet |
+| `no-login` | no `Tailscale-User-Login`, or an empty one |
+| `tagged-node` | no login, and serve's `X-Forwarded-For` is a tailnet address: a node without a user |
+| `login-ambiguous`, `login-malformed` | two login headers, or one that is no login name |
+| `unknown-login` | the login is in no group |
+| `not-allowed` | no group of the login has a rule for this door and capability |
+
+Every refusal is 403 with `{"error": {"code", "message"}}`, the message a fixed sentence; `tagged-node` and `no-login`
+differ only in their label, since a direct local call can send any `X-Forwarded-For`.
+
 ## Token
 
 - Created once with `ensure_token` at first start, after the instance lock.

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""The A2A rules of the probe (FAA-10): what a service that declares `surfaces.a2a` (DEC-0122) serves, read from the
+outside. `a2a_rules(wk, origin, ...)` returns (rule, verdict, evidence) rows, verdicts PASS, FAIL or NOT_RUN:
+
+- `a2a.surface`: `surfaces.a2a` is the schema's (`fabric_a2a.a2a_view`); NOT_RUN when the service declares none;
+- `a2a.card`: the card at `surfaces.a2a.path` answers 200 with a JSON object `agent_card_findings` finds nothing in;
+- `a2a.interface`: the card names an A2A 1.0 JSON-RPC interface on the service origin (local) or on https (remote);
+- `a2a.task-not-found`: `GetTask` of an id nobody made answers JSON-RPC -32001 (TaskNotFound);
+- `a2a.cancel-not-found`: `CancelTask` of that id answers -32001 too;
+- `a2a.method-not-found`: an unknown method answers -32601;
+- `a2a.task-states`: with `probe_text` (a message the service names as safe to send), `SendMessage` answers a message,
+  or a task whose state is an A2A 1.0 state that `GetTask` reads back and `CancelTask` moves to TASK_STATE_CANCELED
+  (or refuses with -32002 when it has already ended); NOT_RUN without one, since a message may start real work.
+
+An interface that answers HTTP 401 makes the binding rules NOT_RUN with the reason: it takes its own key, never the
+descriptor's token (DEC-0122 item 3); give the key through `--key-env` under `use_secret.py run`. It is a command of
+its own beside check_service.py, whose `a2a.card` never calls the card's interfaces (D5); the two say one verdict for the
+card: an unreadable `surfaces.a2a`, and a remote card that answers 401 or 403, are NOT_RUN, never a failure (DEC-0122
+item 2). Standard library only.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import secrets
+import sys
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from fabric_a2a import A2A_PROTOCOL_VERSION, a2a_view, agent_card_findings  # noqa: E402
+from fabric_http import HttpError, request as http_request  # noqa: E402
+
+STATES = ("TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED",
+          "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED")
+Row = Tuple[str, str, str]
+Fetch = Callable[[str, str, Mapping[str, str], Optional[Dict[str, Any]]], Tuple[int, Any]]
+
+
+def http_fetch(method: str, url: str, headers: Mapping[str, str], body: Optional[Dict[str, Any]]) -> Tuple[int, Any]:
+    """One bounded request (10 s, 1 MiB, no retry); the answer's JSON or None."""
+    response = http_request(method, url, headers=dict(headers), body=body, deadline_s=10, retries=0, max_bytes=1 << 20)
+    try:
+        return response.status, response.json()
+    except ValueError:
+        return response.status, None
+
+
+def _rpc(fetch: Fetch, url: str, headers: Mapping[str, str], method: str, params: Dict[str, Any]) -> Tuple[int, Any]:
+    return fetch("POST", url, dict(headers, **{"A2A-Version": A2A_PROTOCOL_VERSION, "Content-Type": "application/json"}),
+                 {"jsonrpc": "2.0", "id": secrets.token_hex(4), "method": method, "params": params})
+
+
+def _code(answer: Any) -> Optional[int]:
+    return answer["error"].get("code") if isinstance(answer, dict) and isinstance(answer.get("error"), dict) else None
+
+
+def a2a_rules(wk: Any, origin: str, *, fetch: Fetch = http_fetch, headers: Optional[Mapping[str, str]] = None,
+              remote: bool = False, descriptor_header: str = "Authorization", probe_text: Optional[str] = None) -> List[Row]:
+    """The A2A rows for one service read at `origin`; `headers` carries the interface's own key, never the token."""
+    rows: List[Row] = []
+    view = a2a_view(wk)
+    if not view["declared"]:
+        return [("a2a.surface", "NOT_RUN", "the service declares no surfaces.a2a")]
+    if not view["valid"]:  # as check_service_rules.a2a_card_verdict: a host does not know where the card is
+        return [("a2a.surface", "NOT_RUN", "surfaces.a2a is not readable (well-known.a2a): "
+                 + "; ".join(f["message"] for f in view["findings"]))]
+    rows.append(("a2a.surface", "PASS", "surfaces.a2a at %s" % view["path"]))
+    try:
+        status, card = fetch("GET", origin.rstrip("/") + view["path"], {"Accept": "application/json"}, None)
+    except (HttpError, OSError) as exc:
+        return rows + [("a2a.card", "FAIL", "the card did not answer: %s" % exc)]
+    if remote and status in (401, 403):
+        return rows + [("a2a.card", "NOT_RUN", "HTTP %d: 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)]
+    if status != 200 or not isinstance(card, dict):
+        return rows + [("a2a.card", "FAIL", "the card answered HTTP %d%s" % (status, "" if isinstance(card, dict) else ", not a JSON object"))]
+    findings = agent_card_findings(card, origin=None if remote else origin.rstrip("/"), remote=remote,
+                                   descriptor_header=descriptor_header)
+    rows.append(("a2a.card", "FAIL" if findings else "PASS", "; ".join(f["message"] for f in findings) or "%d skills" % len(card.get("skills") or [])))
+    url = next((i.get("url") for i in card.get("supportedInterfaces") or [] if isinstance(i, dict)
+                and i.get("protocolBinding") == "JSONRPC" and i.get("protocolVersion") == A2A_PROTOCOL_VERSION
+                and isinstance(i.get("url"), str)), None)
+    if url is None:
+        return rows + [("a2a.interface", "FAIL", "the card names no A2A %s JSON-RPC interface" % A2A_PROTOCOL_VERSION)]
+    rows.append(("a2a.interface", "PASS", url))
+    sent = dict(headers or {})
+    nobody = "probe-" + secrets.token_hex(12)
+    checks = (("a2a.task-not-found", "GetTask", {"id": nobody}, -32001), ("a2a.cancel-not-found", "CancelTask", {"id": nobody}, -32001),
+              ("a2a.method-not-found", "ProbeNoSuchMethod", {}, -32601))
+    for rule, method, params, want in checks:
+        try:
+            status, answer = _rpc(fetch, url, sent, method, params)
+        except (HttpError, OSError) as exc:
+            rows.append((rule, "FAIL", "%s did not answer: %s" % (method, exc)))
+            continue
+        if status in (401, 403):
+            rows.append((rule, "NOT_RUN", "the interface answered HTTP %d: it takes its own key (DEC-0122 item 3); pass it with --key-env" % status))
+        else:
+            got = _code(answer)
+            rows.append((rule, "PASS" if got == want else "FAIL", "%s answered %s, A2A 1.0 says %d" % (method, got if got is not None else "HTTP %d" % status, want)))
+    rows.append(_task_states(fetch, url, sent, probe_text))
+    return rows
+
+
+def _task_states(fetch: Fetch, url: str, headers: Mapping[str, str], probe_text: Optional[str]) -> Row:
+    if not probe_text:
+        return ("a2a.task-states", "NOT_RUN", "no probe message: a message may start real work; pass --probe-text the service names as safe")
+    message = {"role": "ROLE_USER", "parts": [{"text": probe_text}], "messageId": "probe-" + secrets.token_hex(8)}
+    status, answer = _rpc(fetch, url, headers, "SendMessage", {"message": message})
+    result = answer.get("result") if isinstance(answer, dict) else None
+    if status != 200 or not isinstance(result, dict) or not ({"task", "message"} & set(result)):
+        return ("a2a.task-states", "FAIL", "SendMessage answered neither a task nor a message (HTTP %d, code %s)" % (status, _code(answer)))
+    if "message" in result:
+        return ("a2a.task-states", "PASS", "SendMessage answered a message with no task")
+    task = result["task"]
+    if not isinstance(task, dict) or (task.get("status") or {}).get("state") not in STATES:
+        return ("a2a.task-states", "FAIL", "the task's state is not an A2A 1.0 TaskState")
+    read = _rpc(fetch, url, headers, "GetTask", {"id": task.get("id")})[1]
+    if not isinstance(read, dict) or ((read.get("result") or {}).get("status") or {}).get("state") not in STATES:
+        return ("a2a.task-states", "FAIL", "GetTask did not read the task back")
+    cancelled = _rpc(fetch, url, headers, "CancelTask", {"id": task.get("id")})[1]
+    state = (((cancelled or {}).get("result") or {}).get("status") or {}).get("state") if isinstance(cancelled, dict) else None
+    if state == "TASK_STATE_CANCELED" or _code(cancelled) == -32002:
+        return ("a2a.task-states", "PASS", "SendMessage, GetTask and CancelTask agree")
+    return ("a2a.task-states", "FAIL", "CancelTask answered neither TASK_STATE_CANCELED nor -32002")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("origin", help="the service origin, http://127.0.0.1:<port> or its https origin")
+    parser.add_argument("--remote", action="store_true")
+    parser.add_argument("--key-env", help="an environment variable holding the A2A interface's own key (use_secret.py run fills it)")
+    parser.add_argument("--header", default="Authorization")
+    parser.add_argument("--scheme", default="Bearer")
+    parser.add_argument("--probe-text")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    status, wk = http_fetch("GET", args.origin.rstrip("/") + "/.well-known/fabric-service", {"Accept": "application/json"}, None)
+    headers: Dict[str, str] = {}
+    if args.key_env:
+        value = os.environ.get(args.key_env)
+        if not value:
+            print("%s is empty: run under use_secret.py run" % args.key_env, file=sys.stderr)
+            return 2
+        headers[args.header] = "%s %s" % (args.scheme, value) if args.scheme else value
+    rows = a2a_rules(wk if status == 200 else None, args.origin, headers=headers, remote=args.remote, probe_text=args.probe_text)
+    if args.json:
+        print(json.dumps([{"rule": r, "verdict": v, "evidence": e} for r, v, e in rows], indent=1))
+    else:
+        for r, v, e in rows:
+            print("%-8s %-22s %s" % (v, r, e))
+    return 1 if any(v == "FAIL" for _, v, _ in rows) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())