Module capability 

Capability probes — “can this host actually run this tool?”

A skill (or a whole family) may need something the host doesn’t always have: a binary on $PATH, a reachable socket, a configured endpoint, a particular CPU architecture. A capability probe answers that question once, at startup, separately from whether the operator enabled the tool.

The intended flow is three-directional:

1. The dispatcher turns a missing capability into a clean invalid_request error with the reason + a one-line hint — that’s what the calling model sees.
2. Each missing capability is logged once at startup.
3. A status snapshot can carry the per-family state so a dashboard can render a badge with the reason inline.

Probes are stateless: they look at the host (env vars, $PATH, file existence, OS) — not at resolved configuration. Anything config-driven is the operator’s choice and belongs behind a separate “enabled” flag.

Resolution

A tool inherits its family’s probe but may also have its own. resolve runs every probe once and produces a Capabilities map keyed by tool name, applying the combination rule in combine: family Unavailable wins (its hint is usually the more actionable one); otherwise the tool’s own probe applies. Feed each tool’s resolved capability into route_skill_gated — or use routes_gated — to block unavailable tools at dispatch with a reason + hint the caller can act on.

Structs

Capabilities

Effective capability of every tool on this host, plus the raw per-family probe results. Built by resolve once at startup; consulted at dispatch (see route_skill_gated) and useful for a startup log line or a status snapshot.

Enums

SkillCapability

The result of a capability probe.

Functions

combine

Combine a family-level probe with a tool-level probe into the effective capability of one tool. Family Unavailable wins — the family hint is usually the actionable one (e.g. “install ffmpeg”); a tool’s own Unavailable only applies when its family is Ready.

resolve

Run every family and skill probe once and resolve the effective capability of each tool. For each tool: start from its family’s probe (or Ready if the tool belongs to no registered family), then combine it with the tool’s own probe. Tool→family membership is read from each family’s FamilyMeta::tools.