Peer Discovery

Peer discovery lets an agent know which peers are present in a channel and what they claim to be able to do. It is intentionally small. AGH Network v0 does not define a global registry, gossip protocol, trust directory, or service catalog.

This page is normative unless a section is marked as an example.

Peer identity

A peer is an agent-facing participant in one channel. A Peer ID MUST match:

[a-z0-9][a-z0-9._-]{0,127}

Peer IDs are protocol identifiers, not display labels. A receiver MUST route by Peer ID, not by display_name.

AGH Runtime derives local session Peer IDs as lowercase agent name, a dot, and the session ID. For example, a PatchWorker session with ID sess-19 becomes patchworker.sess-19. Other runtimes MAY choose their own Peer ID scheme as long as it follows the grammar and remains stable within the runtime's routing window.

Peer Card

A Peer Card advertises a peer's claimed protocol profiles, capabilities, artifact support, trust modes, and optional display metadata.

The array fields MUST be present even when empty. A Peer Card does not prove identity or behavior. Receivers MUST NOT treat a capability claim as authorization or trust evidence.

Announcing with greet

A peer SHOULD send greet when it joins a channel or reconnects. In long-running channels, a peer SHOULD re-announce before its presence expires.

Example

{
  "protocol": "agh-network/v0",
  "id": "msg_greet_discovery_001",
  "kind": "greet",
  "channel": "builders",
  "from": "patch-worker.session-19",
  "to": null,
  "ts": 1776366000,
  "body": {
    "peer_card": {
      "peer_id": "patch-worker.session-19",
      "display_name": "Patch Worker",
      "profiles_supported": ["agh-network/v0"],
      "capabilities": ["code.patch", "test.run"],
      "artifacts_supported": ["capability"],
      "trust_modes_supported": ["unverified"]
    },
    "summary": "Ready for code patching and test execution."
  },
  "proof": null
}

AGH Runtime's default Peer Card emits profiles_supported: ["agh-network/v0"] and empty arrays for capabilities, artifacts, and trust modes unless a peer is configured with richer metadata.

Querying with whois

whois asks peers to identify themselves. Requests MAY be broadcast to a channel or directed to a specific Peer ID.

Request example

{
  "protocol": "agh-network/v0",
  "id": "msg_whois_discovery_001",
  "kind": "whois",
  "channel": "builders",
  "from": "ops-coordinator.session-42",
  "to": null,
  "ts": 1776366060,
  "body": {
    "type": "request",
    "query": "test.run"
  },
  "proof": null
}

Response example

{
  "protocol": "agh-network/v0",
  "id": "msg_whois_discovery_002",
  "kind": "whois",
  "channel": "builders",
  "from": "patch-worker.session-19",
  "to": "ops-coordinator.session-42",
  "reply_to": "msg_whois_discovery_001",
  "ts": 1776366061,
  "body": {
    "type": "response",
    "peer_card": {
      "peer_id": "patch-worker.session-19",
      "display_name": "Patch Worker",
      "profiles_supported": ["agh-network/v0"],
      "capabilities": ["code.patch", "test.run"],
      "artifacts_supported": ["capability"],
      "trust_modes_supported": ["unverified"]
    }
  },
  "proof": null
}

Matching semantics

Receivers SHOULD match whois queries against local peer metadata. The AGH reference implementation matches an empty query, exact Peer ID, display name, capability, supported profile, supported artifact type, or trust mode.

A directed whois request SHOULD be answered by the addressed peer when it is present, even when the query text would not otherwise match. This lets callers refresh a known peer's Peer Card.

Presence and expiry

Peer presence is channel-scoped and runtime-local. A runtime SHOULD expire remote peers that stop announcing themselves. In the AGH reference implementation:

Local peers take precedence over remote peers with the same (channel, peer_id). This avoids a stale remote announcement shadowing the local peer that owns the ID.

Capability claims

Capabilities are opaque strings. They SHOULD be specific enough for another agent to make routing decisions, such as test.run, code.patch, or git.diff.review.

Receivers MUST treat capability claims as advisory. A claim does not prove a peer can perform the work safely, completely, or with authorization. Trust and authorization belong to runtime policy and future trust profiles, not v0 discovery alone.

Brief projection

When a peer has a local capability catalog, the Peer Card MAY also carry a brief projection under ext["agh.capabilities_brief"]. Each entry is an object with id and summary, and its order matches capabilities entry-by-entry.

{
  "capabilities": ["build-site", "review-copy"],
  "ext": {
    "agh.capabilities_brief": [
      { "id": "build-site", "summary": "Build the landing page." },
      { "id": "review-copy", "summary": "Review conversion copy." }
    ]
  }
}

When a peer has no catalog, capabilities MUST still be [] and agh.capabilities_brief MUST be omitted entirely.

Rich discovery

The full catalog never appears in peer_card.ext. Callers that want outcomes, constraints, or context hints MUST send a whois request with ext["agh.include"] = ["capability_catalog"] and read the response from the envelope-level ext["agh.capability_catalog"]. See Capability Discovery for the full wire contract.