Discovery

The job to be done

Not “save 15 minutes on plist wiring.”

I have a service running and I want other agents to find it and use it without me writing custom wrappers.

That is the pain ASMP targets. Time savings are a side effect.

The flywheel (why self-healing matters)

Most registries are write-once. ASMP is use-often — and every failed lookup is a chance to make the next one free.

flowchart TB
  subgraph broken["Silent failure — every agent pays"]
    A1[Agent queries registry] --> M1[Miss — service exists off-book]
    M1 --> H1[Scavenger hunt · grep · guess ports]
    H1 --> G1[Reinvent or give up]
    G1 --> A2[Next agent — same gap]
    A2 --> M1
  end

  subgraph flywheel["Self-healing — one agent pays, all inherit"]
    B1[Agent queries registry] --> M2[Miss — finds real software]
    M2 --> T[asmp todo / POST /discoveries]
    T --> P[Promote asmp.yaml · scan · announce]
    P --> R[Registry +1 forever]
    R --> B2[Next agent — 250ms hit]
    B2 --> R
  end

	Silent failure	Self-healing flywheel
Cost per agent	~45 min scavenger hunt	~250 ms lookup
Registry growth	0 per miss	+1 per promoted todo
Knowledge	Dies with the session	Compounds across IDEs and agents

When capability lookup is not enough

GET /capabilities?provides=email.ingest returns every service that can ingest email. A vague question — “what should handle this job?” — may need routing evidence (owns, aliases, examples) and host policy when two services score close.

See Routing boundaries.

How discovery works today (without ASMP)

1. Agent starts in a repo
2. Agent has no idea what daemons run on the host
3. Agent greps the filesystem, reads random YAML, guesses ports
4. Or: agent happens to have director-daemon MCP wired in .mcp.json
5. Discovery works in that repo, fails everywhere else

How discovery works with ASMP

1. Software ships asmp.yaml at repo root (or infra/asmp.yaml)
2. Registry scans configured paths and syncs into ~/.asmp/services/
3. Running services can POST /services/announce on start (handshake)
4. Registry indexes capabilities at GET /capabilities?provides=email.classify
5. Every agent session has discovery tools (MCP or HTTP)
6. Agent asks by capability, gets name + endpoint + health + repo
7. On miss: agent drops asmp todo — gap becomes backlog, then manifest

Agent: "I need email classification"
  → service_find(capability="email.classify")
  → director-daemon (healthy, :7400, ~/repos-personal/aic-director-daemon)

Miss with real software nearby:

  → service_find(capability="machine.reach")  # empty
  → found conduit in ~/repos-personal/conduit anyway
  → service_todo(name="conduit", note="fleet SSH sync", repo="~/repos-personal/conduit")
  → later: asmp.yaml + asmp announce
  → next session: service_find(capability="machine.reach")  # hit

Capability naming

Use dot-separated namespaces:

email.ingest
email.classify
email.search
comms.search
process.supervise
finance.ledger
demo.hello

Convention: {domain}.{action} or {domain}.{resource}.{action}.

Agents query by exact match first; registry may suggest partial matches.

Discovery interfaces

Interface	Use case
HTTP API	GET /capabilities?provides=email.classify
MCP tools	service_find, service_list, service_health, service_scan, service_todo, service_todos
CLI	asmp find, asmp scan, asmp todo, asmp todos
File system	Read ~/.asmp/services/ directly
Breadcrumbs	~/.asmp/discoveries.jsonl — gaps agents found but have not registered yet
SDK	asmp.discover("email.classify") (planned)

Self-healing protocol

1

Query first

service_find or asmp find — never grep ports before checking the registry.

2

Miss with evidence

You found real software (process, repo, CLI) that is not in the index.

3

Drop breadcrumb

asmp todo <name> --note "…" or POST /discoveries — append-only, non-destructive.

4

Review backlog

asmp todos or service_todos() — pending notes minus already-registered names.

5

Promote

Author asmp.yaml, then asmp scan or asmp announce. Registry grows; flywheel turns.

Rules:

• Append-only — todos never pretend a service is registered
• Real systems only — not wishlist items
• One painful find → infinite free lookups for every agent after

What discovery does not cover

Need	Protocol
Find a service by capability	ASMP
Invoke a tool on that service	MCP
Talk to another agent as a peer	A2A
Check if access is permitted	Knox / policy
Find where evidence is stored	Omni

ASMP is the shared contact list for services on this machine. Other layers handle invocation, permission, and retrieval.

Announce & discovery

Scan loop, handshake, breadcrumbs

Discover services

Agent-facing patterns