Announce & discovery

Discovery is a handshake, not a one-time file copy.

Four parties

Party	Finds
Service	Registry via ~/.asmp/host.yaml → registry.api
Registry	Services via scan + announce
Scanner	asmp.yaml files on disk
Agent	Services via GET /capabilities or MCP service_find

Services find each other only through the registry — never by grepping ports.

Pull: constant scan

The host scanner walks configured paths (see host profile) and looks for asmp.yaml and infra/asmp.yaml.

asmp scan

Or HTTP:

POST /discover/scan

Response:

{
  "scanned": 12,
  "registered": 3,
  "updated": 9,
  "skipped": 1,
  "stale": 2
}

On boot and on interval (default 5m), the reference runtime runs this automatically.

Push: announce handshake

Running software introduces itself:

asmp announce ./asmp.yaml

Or HTTP:

POST /services/announce

Body: full manifest (from shipped asmp.yaml).

Ack:

{
  "name": "my-service",
  "generation": 4,
  "status": "registered",
  "index_url": "http://127.0.0.1:7700/services/my-service"
}

Stale policy

Services synced from scan that lose their source file or miss last_seen window are marked status: stale — not silently deleted.

Agents should treat stale entries as “was here, not shaking hands anymore.”

Agent discovery

GET /capabilities?provides=email.classify

Or MCP:

service_find(capability="email.classify")

Self-healing: discovery breadcrumbs

Discovery gaps are silent failures — an agent needs a capability, finds nothing, and reinvents or gives up even though the service was right there, just unregistered.

When lookup misses but you observed something real, drop a breadcrumb:

asmp todo mystery-daemon --note "Runs on :9090" --repo ~/repos-aic/mystery

Or MCP:

service_todo(name="mystery-daemon", note="Runs on :9090", repo="~/repos-aic/mystery")

Or HTTP:

POST /discoveries

Rules:

• Append-only — never edits or deletes existing notes
• Existence, not quality — note what you actually saw; do not invent capabilities
• Promote later — asmp todos lists pending notes; author asmp.yaml then asmp scan or asmp announce

The registry gets more complete the more it is used.

Environment overrides

Variable	Default
ASMP_REGISTRY_URL	http://127.0.0.1:7700

Reload

POST /reload

Re-reads ~/.asmp/services/ from disk without scanning sources.