@passioncode-ai/fabric-agent-adapter 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.31.0 - 2026-10-14
+
+An agent is packed, signed and verified as a `fabric-package/1` folder (FAA-27a and FAA-36, `RM-28 pilot`; contract
+DEC-0050, DEC-0051, DEC-0071, DEC-0074, all at the pin `f00a768`).
+
+### Added
+
+- **`fabric_package.py` and `fabric-package.mjs`** (`building-fabric-services`). The two write the same bytes.
+  - `pack <folder>` reads the author's `fabric.package.json` and does the rest:
+    - derives `agentRef` and lists every other file with its SHA-256, in UTF-16 order;
+    - computes the RFC 8785 digest;
+    - checks the result against the contract's schema (bundled at the pin), FAC-SEM-064…066 and FAC-SEM-102, and the
+      folder check.
+    - It refuses symlinks, `.git`, caches and files that are credentials by name, and names each one.
+    - It writes nothing without `--apply`, or while a problem stands.
+  - `sign <folder> --key <file>` adds an Ed25519 (`EdDSA`) publisher signature or organization countersignature over
+    the typed statement.
+    - The key is a JWK or PKCS#8 PEM file at mode 600, which the person names. The kit never makes, keeps or prints a
+      key.
+    - A folder that no longer matches its package is not signed.
+  - `verify <folder> --trust <file>` runs the contract's `verifyPackage` in PK-1…PK-10's order, with the small-order key
+    check first, plus the folder check and the rules.
+  - Also exported: `consumer_placement` / `consumerPlacement` for a consumer agent's `requires.mcp`.
+- **`npx @passioncode-ai/fabric-agent-adapter pack|sign|verify`**: the same commands from the npm package.
+- **`references/package.md`**: what a package is, the author's file, the three commands, a consumer agent, and what this
+  version does not do. That list: ES256 (Fabric D2), hub and passkey signing, the passkey countersignature, Fabric
+  recording packages by `agentRef`, and `publish`.
+
+### Evidence
+
+- `test/fixtures/contract/vendor_vectors.mjs` now writes `package-vectors.json`, with every case re-answered by the
+  contract's own functions, and the bundled schema. The other vendored files came out byte-identical.
+- The Python and Node tests each hold 17 cases:
+  - every verifier case;
+  - every signature reproduced from the vector seeds;
+  - every fixture through the schema, and every semantic fixture through the rules;
+  - pack rebuilding the vector package byte for byte;
+  - both kits packing and signing one folder to the same bytes.
+
+  `test/test_installer.py` covers the npm commands. 28 planted defects were all caught, three of them after a case was
+  added for them.
+- A scenario eval (`package-pack-sign`) and three trigger queries were written before the prose.
+
 ## 0.30.0 - 2026-10-13
 
 The Node service kit installs and uninstalls a launchd job, as the Python kit does (FAA-04). The probe fails a plist

package/README.md

@@ -231,6 +231,18 @@ python3 "$SKILL_DIR/scripts/adapt_project.py" check /path/to/project \
   --contract /path/to/fabric-agent-contract --json
 ```
 
+Pack, sign and verify an agent as a `fabric-package/1` folder (contract DEC-0050, DEC-0051; nothing is written without
+`--apply`, and the key file is the person's, never made or kept here):
+
+```bash
+npx @passioncode-ai/fabric-agent-adapter pack ./example-agent            # the digest, agentRef and every problem
+npx @passioncode-ai/fabric-agent-adapter pack ./example-agent --apply
+npx @passioncode-ai/fabric-agent-adapter sign ./example-agent --key ./publisher.jwk --apply
+npx @passioncode-ai/fabric-agent-adapter verify ./example-agent --trust ./trust.json
+```
+
+See [the package reference](plugins/fabric-agent-adapter/skills/building-fabric-services/references/package.md).
+
 Scaffolding is non-destructive by default. It writes only the paths declared in the
 [delivery brief](docs/evidence/specs/2026-08-27-brief.md) and refuses collisions.
 

package/bin/fabric-agent-adapter.js

@@ -31,6 +31,14 @@ Usage:
       remove plain ~/.claude/skills copies that shadow the installed plugin
   npx @passioncode-ai/fabric-agent-adapter --help
 
+Packages (fabric-package/1):
+  npx @passioncode-ai/fabric-agent-adapter pack <folder> [--apply]
+      list the folder's files, derive agentRef, compute the digest, check it
+  npx @passioncode-ai/fabric-agent-adapter sign <folder> --key <file> [--kid <kid>] [--role publisher|organization] [--apply]
+      add an Ed25519 signature from a private key file (never made or kept here)
+  npx @passioncode-ai/fabric-agent-adapter verify <folder> --trust <trust.json> [--countersigned]
+      check the folder and its signatures against the keys you pin
+
 Claude Code (recommended):
   claude plugin marketplace add ${REPO}
   claude plugin install ${PLUGIN_ID}
@@ -162,4 +170,11 @@ function main(argv) {
   return 0;
 }
 
-process.exit(main(process.argv));
+const PACKAGE_COMMANDS = ['pack', 'sign', 'verify'];
+if (PACKAGE_COMMANDS.includes(process.argv[2])) {
+  // The package commands live in the kit (fabric-package.mjs), one implementation for the skill and this CLI.
+  const kit = path.join(ROOT, 'plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-package.mjs');
+  import(require('url').pathToFileURL(kit).href).then((m) => { process.exitCode = m.main(process.argv.slice(2)); });
+} else {
+  process.exit(main(process.argv));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.30.0"
+  version: "0.31.0"
   contract-version: "0.1.0"
   contract-commit: "f00a7685e3861c27f7899c033fb850a145a1708f"
 ---

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

@@ -8,16 +8,17 @@ description: >-
   "make this agent a local service", "make an online dashboard a Fabric service", "add the
   well-known endpoint", «расходы агента на модели». Covers fabric-service/0.1:
   surfaces, token and one-time login, state, one copy, launchd, descriptor, well-known document,
-  events, the usage report; online: the https guard, the token-gated well-known document, the
-  __Host- cookie; the board responder (fenced claims); Python, Node and dashboard kits, probes.
+  events, the usage report; online: the https guard, token-gated well-known, the
+  __Host- cookie; the board responder (fenced claims); Python, Node and dashboard kits, probes;
+  packing and signing (fabric-package/1).
   NOT for a one-off script or cron job, a hosted product
-  with no agent behind it, the provider manifest (adapting-projects-to-fabric), or building Fabric
+  with no agent, the provider manifest (adapting-projects-to-fabric), or building Fabric
   Dashboards.
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.30.0"
+  version: "0.31.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "f00a7685e3861c27f7899c033fb850a145a1708f"
@@ -271,6 +272,23 @@ Then prove the lock: start a second copy by hand against the same data directory
 must exit 75 while the first keeps serving. Prove recovery: `kill -9` the launchd pid;
 the well-known document must answer again with a new pid within about 15 seconds.
 
+## Packing and signing it — `fabric-package/1`
+
+To hand an agent to another machine or an organization, pack it as one folder (contract DEC-0050, DEC-0051). Write the
+author's `fabric.package.json` (the descriptive fields; for an agent `resultSignal` and `evals` with the receipt of the
+suite as packed), then:
+
+```bash
+python3 <skill-dir>/scripts/fabric_package.py pack <folder>            # or: node fabric-package.mjs, npx @passioncode-ai/fabric-agent-adapter pack
+python3 <skill-dir>/scripts/fabric_package.py pack <folder> --apply
+python3 <skill-dir>/scripts/fabric_package.py sign <folder> --key <key file> --kid <kid> --apply
+python3 <skill-dir>/scripts/fabric_package.py verify <folder> --trust <trust.json>
+```
+
+`pack` derives `agentRef`, lists every file with its SHA-256, computes the digest and checks the schema, the rules and
+the folder; it refuses `.env`, keys, `.git`, caches and symlinks. `sign` uses a key file the person names (Ed25519,
+`EdDSA`); it never makes, keeps or prints a key. Read [the package reference](references/package.md) before packing.
+
 ## The repository around the service
 
 **For a PassionCode.ai repository**, the service's repository follows the organization's

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

@@ -0,0 +1,102 @@
+# Packing, signing and verifying — `fabric-package/1`
+
+Contract DEC-0050 (format and digest), DEC-0051 (signatures), DEC-0071 and DEC-0074 (a consumer agent), rules
+`FAC-SEM-064`…`066` and `FAC-SEM-102`, all at this plugin's pin. The kit: `scripts/fabric_package.py` and
+`scripts/fabric-package.mjs`, which write the same bytes, and `npx @passioncode-ai/fabric-agent-adapter pack|sign|verify`.
+
+## Contents
+
+- [What a package is](#what-a-package-is)
+- [The author's file](#the-authors-file)
+- [pack](#pack)
+- [sign](#sign)
+- [verify](#verify)
+- [A consumer agent](#a-consumer-agent)
+- [What this version does not do](#what-this-version-does-not-do)
+
+## What a package is
+
+One version of an agent or a skill set, as one folder: `fabric.package.json` at its root, every other file listed in it
+with its SHA-256. The digest is SHA-256 over the RFC 8785 form of the document without `digest` and `signatures`, so it
+covers every file through `files[]`, and a countersignature needs no repacking. A folder that is a Claude Code plugin
+has `.claude-plugin/plugin.json` whose `name` and `version` are the package's `id` and `version`.
+
+## The author's file
+
+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 |
+| 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
+receipt; `pack` names the digest it expects. Never edit the receipt to match.
+
+## pack
+
+```bash
+python3 scripts/fabric_package.py pack <folder>           # a dry run: the package, the digest, every problem
+python3 scripts/fabric_package.py pack <folder> --apply   # writes fabric.package.json when nothing is wrong
+```
+
+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.
+
+Then every problem is listed, each with its `rule`: `schema` (the contract's schema), `FAC-SEM-064` (whole: its own
+digest, each path once, every named file listed with the same SHA-256), `FAC-SEM-065` (no secret), `FAC-SEM-066`
+(`agentRef` derived), `FAC-SEM-102` (one role, one server) and `folder` (`file-missing`, `file-digest`, `file-unlisted`,
+`plugin-manifest`, `provider-manifest`). With a problem, `--apply` writes nothing. Repacking drops old signatures and
+says so: a changed package is signed again.
+
+## sign
+
+```bash
+python3 scripts/fabric_package.py sign <folder> --key <key file> [--kid <kid>] [--role publisher|organization] --apply
+```
+
+- The key is a file the person names: an Ed25519 private JWK (`kty` OKP, `crv` Ed25519, `d`, its `kid`) or a PKCS#8 PEM
+  from `openssl genpkey -algorithm ed25519` (then `--kid`). It must be mode 600. The kit never makes, keeps or prints a
+  key; where the key lives is the person's decision (contract v4 D3).
+- The signature covers `{"type": "fabric-package-signature/1", "role", "digest"}` in RFC 8785 form, so a publisher's
+  signature never stands for a countersignature. `alg` is `EdDSA`, the one algorithm DEC-0051 admits.
+- Only a package that is whole and matches its folder is signed. A publisher signature is always one (re-signing replaces
+  it); an organization countersignature under the same `kid` is replaced, another is added.
+- The answer carries `publicKey`, the public JWK the installing machine pins (the estate record's `publisherKeys`,
+  DEC-0055). The package names a publisher, never a key.
+
+## verify
+
+```bash
+python3 scripts/fabric_package.py verify <folder> --trust trust.json [--countersigned]
+```
+
+`trust.json` is `{"publisher": [jwk…], "organization": [jwk…]}`, the keys this machine pins. The verdict is the
+contract's `verifyPackage`, in PK-1…PK-10's order: `malformed`, `digest-mismatch`, `unsigned`, `no-publisher-signature`,
+then per signature `unknown-algorithm`, `unknown-key` / `duplicate-kid`, `key-algorithm-mismatch` / `unusable-key`,
+`small-order-key` (checked before any verification, DEC-0045), `bad-signature`, and with `--countersigned`
+`no-countersignature`. A countersignature under a key the machine does not pin is listed in `unverified` unless
+`--countersigned` is asked; a bad one under a pinned key refuses the package. `verify` also runs the folder check and the
+rules, so a file changed after signing is caught (`file-digest`, `file-unlisted`).
+
+Exit codes for all three: 0 when it holds, 1 when it does not, 2 for a usage error. The answer is JSON on stdout.
+
+## A consumer agent
+
+An agent that serves nothing and only calls MCP servers is `kind: agent` without `provider` (DEC-0071). It lists its
+`skills` and its plugin manifest, has no `service`, `state` or `layer`, and names the servers it calls in `requires.mcp[]`
+by role and tools. A role names the secret slots that configure its server (`secrets`, DEC-0074), each declared in
+`secrets[]`, one slot to one role. Before installing, `consumer_placement(pkg, configured)` / `consumerPlacement(pkg,
+Map)` names each role the placement does not register and each tool its server lacks.
+
+## What this version does not do
+
+- **ES256.** It waits for Fabric's decision D2; until then a verifier refuses it as `unknown-algorithm` (FAA-29).
+- **Hub signing for the person's own machines, and the passkey.** Stage 3 of target architecture v4.
+- **The organization's countersignature as a passkey assertion.** It waits for `org-countersign/1` and
+  `org-authority/1`; this version's countersignature is a detached Ed25519 signature.
+- **Fabric recording packages by `agentRef`.** It waits for the ADR-0138 D2b amendment.
+- **`publish --to org`** (FAA-28).