Discover Capabilities#

Query the mesh by what you need, not by who has it. There is no registry to ask and no address to know: every node folds the announcements it hears into a local index, and discovery is a read of that index.

Two surfaces, two questions#

Filter nodes answers which machines fit — GPUs with enough VRAM, a region, a model, a tag you invented. It returns node ids. This is placement.

List tools answers what can I call — the named, schema'd operations peers have announced. It returns descriptors. This is the agent surface, and it is what lowers into an LLM's tool array.

The same announcement can feed both.

Discovery is a local read#

Both surfaces read the node's own folded index. Nothing goes on the wire when you call them, which has three consequences worth holding onto:

• They are fast and synchronous in the bindings whose types allow it. A discovery call is not a network round trip.
• They can be empty and correct. An announcement that has not arrived yet is indistinguishable from one that was never made.
• They are a snapshot. The answer was true when the index last changed, not necessarily now.

Folding takes a moment — do not poll for it#

An announcement propagates asynchronously, and multi-hop: a match can come from a node several hops away that you have never connected to. So the index right after a peer announces is often still empty.

The wrong fix is a polling loop. Every binding exposes a watch: take a list baseline, then subscribe, and changes are pushed the moment the fold mutates. It is event-driven off the fold's change signal, so an idle mesh costs zero periodic work.

Each binding's watch takes an optional interval. It is a staleness ceiling, not a poll rate — a safety-net re-diff at least that often. Leave it unset for pure event-driven behaviour. Reading it as "how often to check" produces a timer nobody needed.

Discovery is advisory#

Finding a node that can do something gets you no claim on it. There is no exclusivity in a discovery result, no reservation, and no promise the node will still be there when you call.

If you need to atomically claim a contended exclusive resource — a GPU island, an accelerator slot, a licensed seat — that is the gang-claim scheduler, not find_nodes. Using discovery as a booking system is how two callers end up believing they own the same device.

Seeing is not calling#

A capability you can discover is not a capability you can invoke. Visibility and invocability are separate, and the check happens on invoke — see Errors for what a refusal looks like when it arrives.

Richer predicates (numeric, semver, AND/OR/NOT), the scoping model, and the CLI equivalent (net-mesh cap query --tag …) are in Capabilities.

Discover it — Go#

Filter nodes by capability#

nodes, err := node.FindNodes(net.CapabilityFilter{
    RequireTags: []string{"gpu"},
    MinVRAMGB:   24,
})
if err != nil {
    log.Fatal(err)
}
// nodes is []uint64 — the node ids matching right now.

FindNodes returns ([]uint64, error). The error is not about the query — it is the cgo boundary, which every Go call on this page crosses.

List tools#

raw, err := net.NewMeshRpc(node)
if err != nil {
    log.Fatal(err)
}
rpc := net.NewTypedMeshRpc(raw)
 
tools, err := raw.ListTools()          // on the raw handle
if err != nil {
    log.Fatal(err)
}
for _, t := range tools {
    fmt.Printf("%s v%s tags=%v\n", t.ToolID, t.Version, t.Tags)
}

Two handles, two surfaces: ListTools() is a method on *MeshRpc, while WatchTools and every generic tool function take the *TypedMeshRpc built over it. net.ListTools(rpc) is the package-level form that takes the typed one, so either works — pick one and stay with it.

Watch for changes#

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
 
changes, errs, baseline, err := net.WatchTools(ctx, rpc, net.WatchOptions{})
if err != nil {
    log.Fatal(err)
}
for _, t := range baseline {
    fmt.Printf("baseline %s v%s\n", t.ToolID, t.Version)
}
for {
    select {
    case c := <-changes:
        fmt.Println(c)         // pushed on fold mutation — no ticker
    case err := <-errs:
        log.Println("watch:", err)
    case <-ctx.Done():
        return
    }
}

Go is the only binding that hands you the baseline from the watch call itself, taken before the watch opens — so there is no window between snapshot and subscription to reason about. Elsewhere you take the baseline yourself and rely on the eager subscribe.

WatchOptions.Interval is a time.Duration staleness ceiling. Leave it zero for pure event-driven behaviour.

Verify it worked#

tools, err := raw.ListTools()
if err != nil {
    log.Fatal(err)
}
found := false
for _, t := range tools {
    if t.ToolID == "web_search" {
        found = true
    }
}
if !found {
    log.Fatal("web_search did not fold — is the pair handshaked and started?")
}

Expect the descriptor to arrive without its schemas if the tool was announced from Go — see the seam described in Announce. A tool announced from Rust, TypeScript or Python and discovered from Go carries them.

Next: Invoke a capability.