From 511d808acf6a789cbe85211cec5865da5fbdb201 Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Tue, 28 Apr 2026 14:01:59 -0400 Subject: [PATCH] [runtime] clarify VerifyAgent separation and runtime scope Why: Keep this runtime focused on executing actions and producing signed receipts while moving public verifier product messaging to the external VerifyAgent repo. Contract impact: none --- CHANGELOG.md | 1 + README.md | 26 +++++++++++++++++++++++--- docs/CONFIGURATION.md | 4 ++++ docs/OPERATIONS.md | 4 ++++ server.mjs | 2 +- 5 files changed, 33 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f59087..6e6b24f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this runtime repository will be documented in this file. ## Unreleased +- Separated VerifyAgent into its own public Commons/MIT repository. The runtime now focuses on executing agent actions and producing signed CommandLayer receipts. Public paste-and-verify receipt verification is handled externally by VerifyAgent. - Aligns the runtime service, docs, examples, and package metadata on the CommandLayer Commons v1.1.0 current line. - Removes Commons runtime dependence on inbound `x402` request metadata so public Commons responses remain payment-agnostic. - Refreshes the golden receipt fixture and production-surface tests to match current wrapped receipt responses and verification expectations. diff --git a/README.md b/README.md index a078cde..07af026 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,24 @@ # CommandLayer Runtime -Reference Node.js runtime for CommandLayer Commons verbs. This service exposes deterministic verb handlers, signs receipts with Ed25519 via `@commandlayer/runtime-core`, and verifies receipts with a configured public key or an ENS lookup. +Reference Node.js runtime for CommandLayer Commons verbs. This service executes deterministic verb handlers and produces signed CommandLayer receipts via `@commandlayer/runtime-core` (canonicalization, SHA-256 hashing, and Ed25519 signatures). + +For public paste-and-verify receipt verification, use VerifyAgent: https://github.com/commandlayer/verifyagent + +## Layer boundaries + +- **Runtime (this repo):** executes agent actions and emits signed CommandLayer receipts through versioned runtime endpoints. +- **VerifyAgent (external):** public receipt verifier experience in a separate Commons/MIT repository. +- **SDK:** wraps agents and exposes reusable receipt tooling for programmatic verification and integrations. +- **Agent Cards:** machine-readable identity/capability metadata. +- **Commercial runtime:** hosted runtime surface (paid API, x402, indexing, dashboards). + +## Runtime receipt flow + +1. Runtime receives an agent action request. +2. Runtime executes the verb endpoint. +3. Runtime creates a canonical CommandLayer receipt. +4. Runtime signs the receipt with the configured Ed25519 key. +5. The receipt can be verified locally, by the SDK, or publicly through VerifyAgent. ## What is implemented @@ -9,7 +27,7 @@ The runtime currently exposes: - `GET /` — JSON index with service metadata and enabled verb routes. - `GET /health` — health and signer/verifier readiness. - `GET /healthz` — alias for `/health`. -- `POST /verify` — receipt hash/signature verification, with optional ENS lookup and optional schema validation. +- `POST /verify` — runtime verification API for receipt hash/signature checks, with optional ENS lookup and optional schema validation. - `POST //v1.1.0` for the verbs enabled by `ENABLED_VERBS`. The default enabled verbs are: @@ -158,7 +176,7 @@ scripts/dev.sh `scripts/dev.sh` generates `keys.env` with `tools/mkkeys.mjs` if needed, sources that file, enables debug routes, and starts `server.mjs` on `127.0.0.1:8099` by default. -### Verify locally +### Verify locally (runtime API) ```bash curl -s http://127.0.0.1:8080/health | jq . @@ -183,6 +201,8 @@ The production verification path is `server.mjs`, which signs receipts and verif Repo-local test coverage now includes runtime service tests that exercise the receipt production path and `POST /verify` behavior directly, alongside the remaining legacy helper coverage under `runtime/tests/`. +For public paste-and-verify receipt verification, use VerifyAgent: https://github.com/commandlayer/verifyagent + ## Configuration and operations - Configuration reference: [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 5111303..ac1596b 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -2,6 +2,10 @@ This file documents environment variables that are actually read by `server.mjs` today. +For public paste-and-verify receipt verification, use VerifyAgent: https://github.com/commandlayer/verifyagent + +This runtime repository is focused on execution + signed receipt production, not hosting a public verifier UI/demo. + ## Core listen and service metadata | Variable | Default | Notes | diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 12716e1..41d6992 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -2,6 +2,10 @@ This runbook describes behavior that is implemented by the current repository. +For public paste-and-verify receipt verification, use VerifyAgent: https://github.com/commandlayer/verifyagent + +Boundary reminder: this runtime executes verbs/actions and produces signed CommandLayer receipts; it does not ship the public verifier UI/demo experience. + ## Minimum deployment inputs A normal boot requires all of the following unless `DEV_AUTO_KEYS=1` is used for development: diff --git a/server.mjs b/server.mjs index 9d04d8d..54d678f 100644 --- a/server.mjs +++ b/server.mjs @@ -1799,7 +1799,7 @@ app.post("/verify", async (req, res) => { let ensExpect = null; if (wantEns) { - // ENS signer resolution (VerifyAgent.eth integration) + // ENS signer resolution for receipt verification. // Resolves cl.sig.pub / cl.sig.kid from the signer ENS name so receipts can be verified without hardcoded keys. const signerForEns = String(proof?.signer_id || runtimeConfig.signerId || "").trim(); const ensOut = await fetchEnsSignerBundle({ signerName: signerForEns, refresh });