All plugins

air-agent-kya

Know-Your-Agent with AIR (Moca Network): you delegate your AIR identity to Hermes once in the AIR Console (hermes air login, device code, P-256 agent key, credentials.verify scope, no wallet signing); the kya_visit tool then enters KYA stores that publish /.well-known/air-kya, gets a one-time SD-JWT presentation from AIR that discloses only the claims the store requests (e.g. membership tier), and returns the catalog that credential unlocks; agents that aren't delegated get the store's public catalog. Disclosure — network calls to the AIR Console (sandbox.agents.air3.com, during login only), the AIR API (air.api.sandbox.air3.com) and AIR credential API (credential-testnet.api.sandbox.air3.com), and to each KYA site the agent visits (https only, plain http allowed for localhost); stores a P-256 agent private key and the AIR delegation bundle in its own plugin-data directory with mode 0600, removed by hermes air logout; on first run after the rename it reads the old air-kya plugin-data directory once to carry a delegation over; a live kya_visit asks for approval through Hermes's approval gate before any claim is disclosed and sends the presentation only to the origin that issued the nonce; the model never sees the presentation, key or tokens; endpoints are plugin settings, no secrets or env vars read; no shell, subprocess, background thread or telemetry.

MocaNetworkToolsv0.1.2Updated 18 hours ago

About

Know-Your-Agent with AIR (Moca Network): you delegate your AIR identity to Hermes once in the AIR Console (hermes air login, device code, P-256 agent key, credentials.verify scope, no wallet signing); the kya_visit tool then enters KYA stores that publish /.well-known/air-kya, gets a one-time SD-JWT presentation from AIR that discloses only the claims the store requests (e.g. membership tier), and returns the catalog that credential unlocks; agents that aren't delegated get the store's public catalog. Disclosure — network calls to the AIR Console (sandbox.agents.air3.com, during login only), the AIR API (air.api.sandbox.air3.com) and AIR credential API (credential-testnet.api.sandbox.air3.com), and to each KYA site the agent visits (https only, plain http allowed for localhost); stores a P-256 agent private key and the AIR delegation bundle in its own plugin-data directory with mode 0600, removed by hermes air logout; on first run after the rename it reads the old air-kya plugin-data directory once to carry a delegation over; a live kya_visit asks for approval through Hermes's approval gate before any claim is disclosed and sends the presentation only to the origin that issued the nonce; the model never sees the presentation, key or tokens; endpoints are plugin settings, no secrets or env vars read; no shell, subprocess, background thread or telemetry.

AIR Agent KYA — Hermes plugin

Lets your Hermes agent prove who it acts for. You delegate your AIR identity (Moca Network) to the
agent once, approving it in the AIR Console. When the agent visits a Know-Your-Agent (KYA) store, AIR
issues a one-time proof that discloses only the claim the store asks for (for example your membership
tier). The store checks it and returns the catalog your credential unlocks: public pricing for
everyone, VIP for verified members. You approve each disclosure, the agent never sees your
credential, and it can't sign or spend.

Install

hermes plugins install MocaNetwork/air-agent-hermes --no-enable
hermes plugins enable air-agent-kya          # asks you to approve the Python dependencies
hermes air --help

From a local checkout:

cp -r air-agent-hermes ~/.hermes/plugins/air-agent-kya
hermes plugins validate ~/.hermes/plugins/air-agent-kya --install-deps
hermes plugins enable air-agent-kya

Upgrading from air-kya (≤0.2.1): disable and remove the old plugin, install this one. Your
delegation is carried over; no new login needed.

Quick start

hermes air visit https://kya.demo.air3.com   # not delegated → public (Standard) catalog
hermes air login                             # approve in the AIR Console
hermes air visit https://kya.demo.air3.com   # → VIP catalog (needs Gold Membership, SD-JWT)

In chat: "What does Demo Merch sell and at what prices? https://kya.demo.air3.com", then after
hermes air login: "Check Demo Merch's catalog again."

Commands

Terminal: hermes air …

CommandWhat it does
hermes air login [--name <label>]Delegate your AIR identity to this agent. Prints an AIR Console URL + code; approve it there. Generates the P-256 agent key and stores key + bundle (0600). Default label: Hermes (AIR Agent KYA)
hermes air whoamiShow the stored delegation: delegated, userId, partnerId, Console URL
hermes air logoutDelete the local agent key and bundle. Also revoke the key in the AIR Console
hermes air visit <siteUrl>Enter a KYA store and print the 4-step trace (discover → challenge → AIR → catalog) and its catalog
hermes air visit <siteUrl> --mock <profile>Same, against a local mock-mode site using npm run mock-air
hermes air visit <siteUrl> --jsonPrint only the catalog JSON
hermes air --helpList commands

Mock profiles: good (eligible), low-tier, wrong-class, expired, bad-signature,
untrusted-issuer, wrong-vct, missing-disclosure, overshare, unbound, no-credential.

In chat

CommandWhat it does
/air whoamiDelegation status (same as hermes air whoami)

Login is deliberately terminal-only, so the model can never delegate itself.

Agent tools (the model calls these)

ToolArgsWhat it does
kya_visitsite, optional mock_profileFull KYA handshake; returns viewer, reason, verification, disclosed claim names and the catalog. Never returns the credential. Live sites trigger an approval prompt before AIR discloses
air_whoami—Read-only delegation status

The bundled skill air-agent-kya:air-agent-kya tells the model when to use them and how to read
the outcomes.

Plugin management

CommandWhat it does
hermes plugins validate <path> --install-depsCheck the manifest, load the plugin, install deps (same check catalog CI runs)
hermes plugins doctor <path> --ciHealth check
hermes plugins enable air-agent-kya / disable air-agent-kyaTurn the plugin on / off
hermes plugins update air-agent-kyaUpdate; your delegation in plugin-data survives

Outcomes

ResultMeaning
viewer: eligibleVerified agent → VIP catalog
verification: not_delegatedNo delegation; agent sent an empty proof → public catalog
verification: NotFoundThe delegated AIR account has no credential matching the site's program
verification: Non-Compliant / reason: condition_not_met:*Credential found, rule not met (e.g. Silver tier)
code: policy_not_configuredSite's AIR policy incomplete (missing lists what)
MOCK_REQUIRED / MOCK_REJECTEDSite mode and --mock don't match
agent/session 401/403Key revoked or replaced → hermes air login again
retryable: trueAIR storage outage (CREDENTIAL_STORAGE_UNAVAILABLE); retry later

Settings

All optional; set them in Hermes Desktop → Plugins → AIR Agent KYA, or under
plugins.entries.air-agent-kya.settings in Hermes config. Empty endpoint settings use the AIR
sandbox (same defaults as agent/air.ts); the delegation bundle's partnerId wins over partner_id.

SettingDefault
require_approvaltrue: ask before a live kya_visit discloses claims
allow_local_sitesfalse: let kya_visit reach localhost sites outside mock mode (private and link-local addresses stay blocked)
partner_idAIR AI Studio sandbox partner 8ab60850-bdfa-4e48-8afa-d67a3d715224
console_urlhttps://sandbox.agents.air3.com
api_urlhttps://air.api.sandbox.air3.com/v2
credential_api_urlhttps://credential-testnet.api.sandbox.air3.com
agent_dirThis profile's plugin-data/air-agent-kya/
mock_air_urlhttp://127.0.0.1:8799 (mock-mode sites only)

Disclosures

What this plugin does that you may want to know before installing:

  • Network calls: the AIR Console (sandbox.agents.air3.com, during hermes air login only), the
    AIR API (air.api.sandbox.air3.com) and AIR credential API
    (credential-testnet.api.sandbox.air3.com), and each KYA site the agent visits
    (/.well-known/air-kya, /kya/challenge, /catalog). https only, and only to public addresses:
    each connection resolves the host, refuses private, loopback, link-local and cloud-metadata
    addresses, and connects to the address it checked. Localhost (http or https) only in mock mode or
    with allow_local_sites.
  • Stored credentials: a P-256 agent private key and the AIR delegation bundle, in the plugin's own
    plugin-data directory, mode 0600. hermes air logout deletes them; revoke the key in the AIR
    Console too.
  • What leaves AIR: only the SD-JWT claims a site requests, only after you approve (default), and
    only to the origin that issued the nonce. The model never receives the presentation, key or tokens.
  • Reads outside its own data: once, the old air-kya plugin-data directory, to carry over a
    delegation made before the rename.
  • Does not: run shell commands or subprocesses, start background processes, read .env or other
    credential stores, sign transactions, or send telemetry.

Protocol parity with mocaverse/air-kya

StepRepo (npm run agent)Plugin
Delegatelogin (AIR Console device code, air-agent-broker, openid credentials.read credentials.verify)hermes air login
Session proof${pubPem}:${userId}:${ts}, DER ECDSA b64, strictly increasing tssame
Partnerbundle → configured partner → AI Studio sandboxsame
Scopeverify-only, fall back to read+verifysame
Presentationvp_token[programId][0] or verifiableCredential[0](.id)same
Site/.well-known/air-kya, POST /kya/challenge, GET /catalog + X-AIR-KYA (empty when none)same

Layout

air-agent-hermes/
├── plugin.yaml               manifest: tools, hook, deps, settings, requires_hermes
├── __init__.py               register(ctx)
├── schemas.py                tool schemas (model-facing)
├── tools.py                  handlers, approval hook, `hermes air` CLI, `/air`
├── air.py                    AIR client: device-code login, P-256 key, session, verify-by-agent
├── kya.py                    site visit: discovery → challenge → AIR → catalog
├── skills/air-agent-kya/     when/how the model uses it
├── tests/                    test_flow.py (offline), e2e_local.py (real Worker + mock AIR)
├── docs/                     catalog entry draft + catalog PR text
└── .github/workflows/ci.yml  unit + e2e

Development

pip install -r requirements-dev.txt
python -m pytest tests -q              # offline, all AIR and site calls mocked

# e2e: in mocaverse/air-kya run `npm run dev` and `npm run mock-air`, then
python3 tests/e2e_local.py             # all 11 mock profiles against the real Worker

Releasing

  1. Bump version in plugin.yaml, add a CHANGELOG.md entry, merge to main with CI green.
  2. Direct installs (hermes plugins install MocaNetwork/air-agent-hermes) pick it up on
    hermes plugins update air-agent-kya.
  3. Hermes catalog: open a PR to NousResearch/hermes-agent bumping sha (full 40-char commit) and
    version in plugin-catalog/air-agent-kya.yaml. First listing: see docs/catalog-entry.yaml
    and docs/catalog-pr.md.

License

MIT — see LICENSE.

README from the reviewed commit 76da8a0; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section