# Eclipse Herald MCP

**Powered by Cyan Eclipse Technologies** — https://cetech.ai

**Eclipse Herald — the agent-to-agent discovery and delegation layer for Cyan Eclipse Technologies: signed Agent Cards, policy-gated delegation, certification before hire.**

## Why this exists

Eclipse Bazaar's Phase 3 is agent-to-agent commerce: agents finding,
verifying, hiring, and paying each other. The wire protocol for that already
exists as an open standard — **A2A (Agent2Agent)**. Herald is CETech's
implementation stance on it: the herald *proclaims* who our agents are
(signed cards), *carries* our mandates outward (the gateway), and *announces*
who else may be trusted (certify-before-you-hire). Blueprint:
`~/workspace/cyan-eclipse/eclipse-herald-a2a-blueprint-20261025.md`.

## Status

**v0.1.0 — H0/H1 local implementation. In development; bench pending; NO
certification claimed.** Local only: no network calls, no live third-party
agents, no real money (settlement is in zero-value TEST-CREDITS). Cards are
signed and verifiable; delegation runs against local stub agents. Live task
endpoints and external counterparties are H2/H3 scope.

## What v0.1 does

- **Agent Card toolkit** — builds A2A v1.0-shaped cards for the four hireable
  service faces (Test Bench, Verity audit, Argus research, Silas engineering)
  from `card_templates.json`; validates schema; signs with a locally
  generated RSA key (JWS/RS256, detached signature in the card's
  `signatures` array); exports the public JWKS. Signed cards for all four
  faces live in `cards/`; the public key document is `keys/jwks.json`.
- **Key custody** — the private key is a single local file,
  `keys/signing-key.json`, **chmod 600**, generated on first use. It is never
  printed, logged, or embedded in any document. (Owner: keep a backup in your
  password manager, same pattern as the Memory Vault key.)
- **Gateway core** — discover (local card file) → verify JWS → certify-check
  (card must carry a CERTIFIED verdict reference whose scope covers the
  requested skill) → **mandate** (AP2-shaped: task hash, counterparty card
  hash, budget cap, expiry) → dispatch to a local stub agent → delivery
  validation → **receipt-on-delivery**: the settlement record is written
  only when an artifact actually arrives. No artifact, no payment.
- **Security Law #1, enforced in the code path** — foreign-agent output
  INFORMS; it never INSTRUCTS. Deliverables pass through a quarantine
  ingest that strips instruction-shaped lines into a flagged list and wraps
  the remainder as labeled data with provenance. A test proves an injected
  instruction in a deliverable changes nothing about gateway behavior.
- **Receipts ledger** — append-only, hash-chained JSONL (`receipts.jsonl`):
  mandates, refusals, deliveries. The chain is verifiable; tampering breaks
  it detectably.

## Tools (5, MCP + CLI parity)

| Tool | What it does |
|---|---|
| `card_build` | Build an unsigned card for a face from its template. |
| `card_sign` | Build + sign a card; write it to `cards/`; export JWKS. |
| `card_verify` | Schema-validate a card and verify its JWS signature. |
| `gateway_delegate` | Governed delegation to a LOCAL test agent (echo, research-stub, silent, injecting). |
| `receipt_list` | Read the ledger + verify the hash chain. |

## Run it

```bash
python3 server.py                       # MCP over stdio, stdlib only
python3 herald_cli.py keygen            # one-time: signing key + JWKS
python3 herald_cli.py sign argus-research
python3 herald_cli.py verify cards/argus-research.agent-card.json
python3 herald_cli.py delegate cards/argus-research.agent-card.json research-stub research-brief 5.00 "Why did BTC move today?"
python3 herald_cli.py receipts
python3 -m unittest discover -s tests   # 17 tests
```

Env overrides: `HERALD_KEY_PATH`, `HERALD_LEDGER`, `HERALD_CARDS_DIR`,
`HERALD_JWKS`.

## Roadmap

- **H2** — Gateway dogfood against our own live service endpoints (Eclipse
  Connect relay pattern); internal worker-desk cards.
- **H3** — Bazaar P3: certify-before-you-hire as a paid service; external
  counterparties; real settlement behind the same mandate/receipt flow.

## License / attribution

A Cyan Eclipse Technologies product. The "Powered by Cyan Eclipse Technologies" attribution travels with it.