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 — TypeScript#

Filter nodes by capability#

const peers: bigint[] = node.findNodes({
  requireTags: ['gpu'],
  minVramGb: 16,
});

findNodes is a method on the MeshNode and is synchronous — it reads the local index. Node ids come back as bigint[] because they are 64-bit; === against a number literal is always false.

minVramGb and minMemoryGb are in gigabytes, matching every other binding and the substrate. They were spelled minVramMb / minMemoryMb before 0.35, which is a different name from the one the native layer reads — so both were dropped and the threshold matched everything. Rename and rescale together: a minVramMb: 16_384 that used to be ignored is minVramGb: 16, not 16_384.

findNodesScoped(filter, scope) narrows to a tenant, region or subnet pool.

Pick one node#

const target: bigint | null = node.findBestNode({
  filter: { requireTags: ['gpu'] },
  preferMoreVram: 1,
});

findBestNode applies the requirement's weights and returns one winner instead of the whole matching set. The four weights — preferMoreMemory, preferMoreVram, preferFasterInference, preferLoadedModels — each score one axis of what a candidate announced about itself: system memory, GPU VRAM, model inference speed, and the share of its models already loaded. They must be finite: NaN and Infinity throw, while finite values outside [0, 1] are clamped by the substrate. Ties, including the case where every weight is omitted, resolve to the lowest matching node id.

null means nothing matched. 0n is a real node id, so test === null rather than falsiness. findBestNodeScoped(requirement, scope) applies the scope first, so a peer outside it cannot win on capacity.

Same local-index read as findNodes: synchronous, no network, and only peers whose announcements have already arrived.

List tools#

listTools and watchTools take the node directly:

import { listTools, watchTools } from '@net-mesh/sdk';
 
for (const t of listTools(node)) {
  console.log(`${t.toolId} v${t.version}  tags=${t.tags}`);   // baseline
}

findNodes, listTools and watchTools all take the MeshNode. Only the tool-serving and tool-calling surface needs the RPC handle, which node.rpc() returns.

Schemas arrive as JSON-encoded strings on descriptor.inputSchema and descriptor.outputSchema. Call JSON.parse before handing them to anything that expects an object.

Watch for changes#

const controller = new AbortController();
 
for await (const change of watchTools(node, { signal: controller.signal })) {
  console.log(change);   // pushed on fold mutation — no timer, no re-diff
}

options.intervalMs is the staleness ceiling; leave it unset for pure event-driven behaviour. Abort the signal to end the loop — the iterator subscribes eagerly at call time, so a change published before you start iterating is still observed.

Lower a descriptor for an LLM#

import { openai } from '@net-mesh/sdk';
 
const lowered = listTools(node).map(openai.toOpenaiTool);

anthropic, mcp and gemini are namespaced objects beside it, each with a lower* counterpart that parses a model's reply into a call spec.

Verify it worked#

const found = listTools(node).some((t) => t.toolId === 'web_search');
if (!found) {
  throw new Error('web_search did not fold — is the pair handshaked and started?');
}

Next: Invoke a capability.