Documentation
¶
Overview ¶
Package agentregistry is a read-only catalog client for the Agent Client Protocol (ACP) agent registry — the published list of ACP-speaking agents at https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json.
It is a CATALOG to seed from, not an installer. contenox never downloads, extracts, or verifies an agent's archive, and never manages a binary directory: it only ever *invokes* agents the user already has installed, or that run-time fetchers like npx/uvx pull down themselves. Resolve therefore turns a catalog entry into a RunSpec (a bare command + args + env the runtime can spawn), never into anything on disk.
Index ¶
Constants ¶
const ( MethodNPX = "npx" MethodUVX = "uvx" MethodBinary = "binary" )
Distribution method names observed in the registry's `distribution` map.
const DefaultRegistryURL = "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json"
DefaultRegistryURL is the canonical location of the ACP agent registry catalog. Fetch GETs this unless Client.URL overrides it.
Variables ¶
This section is empty.
Functions ¶
func PlatformKey ¶
PlatformKey maps a Go runtime.GOOS/GOARCH pair to the registry's "<os>-<arch>" distribution key (e.g. linux/amd64 -> "linux-x86_64", darwin/arm64 -> "darwin-aarch64"). GOOS tokens (linux, darwin, windows) match the registry directly; only the arch token is translated.
Types ¶
type Client ¶
type Client struct {
URL string // catalog URL; defaults to DefaultRegistryURL
CachePath string // local cache file path (e.g. <dataDir>/agent-registry.json)
HTTP *http.Client // HTTP client; defaults to one with defaultTimeout
}
Client fetches and caches the registry catalog. The zero value is not usable; construct one with NewClient.
func NewClient ¶
NewClient returns a Client that caches the catalog at cachePath and fetches from DefaultRegistryURL.
func (*Client) Fetch ¶
Fetch returns the registry catalog.
When refresh is false and a readable cache exists, the cache is returned without any network access — the common `agent search` / `agent add` path stays offline and fast. When refresh is true (or no usable cache exists), it GETs the catalog, writes it to the cache (best-effort), and returns it. On a network or HTTP error it falls back to the cache if one is present, so a transient CDN outage doesn't break the command; only when there is no cache to fall back to does the network error surface.
type Registry ¶
type Registry struct {
Version string `json:"version"`
Agents []RegistryAgent `json:"agents"`
Extensions json.RawMessage `json:"extensions,omitempty"`
}
Registry is the top-level catalog document.
type RegistryAgent ¶
type RegistryAgent struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description"`
Repository string `json:"repository,omitempty"`
Authors []string `json:"authors,omitempty"`
License string `json:"license,omitempty"`
Website string `json:"website,omitempty"`
Icon string `json:"icon,omitempty"`
Distribution map[string]json.RawMessage `json:"distribution"`
}
RegistryAgent is one catalog entry. Distribution is kept as raw JSON per method because each method ("npx"/"uvx"/"binary") has a different shape; Resolve decodes only the method it selects.
func Find ¶
func Find(reg *Registry, id string) (RegistryAgent, bool)
Find returns the catalog entry with the given id (exact match).
func List ¶
func List(reg *Registry) []RegistryAgent
List returns every catalog entry (a copy, safe to sort/filter).
func Search ¶
func Search(reg *Registry, query string) []RegistryAgent
Search returns catalog entries whose id, name, or description contains query (case-insensitive). An empty query returns the full catalog.
type RunSpec ¶
type RunSpec struct {
Command string // executable to spawn (e.g. "npx", "uvx", "goose")
Args []string // arguments passed to Command
Env map[string]string // extra environment the agent expects (never nil)
Method string // distribution method used: "npx" | "uvx" | "binary"
Note string // human note, e.g. a PATH requirement for binary agents
}
RunSpec is how to spawn an agent, resolved from a catalog entry for a concrete OS/arch. It is a run recipe only: Command is a bare executable the runtime hands to exec (npx/uvx, or a binary basename the user must have on PATH), never a path into anything contenox installed.
func Resolve ¶
func Resolve(a RegistryAgent, goos, goarch string) (RunSpec, error)
Resolve turns a catalog entry into a RunSpec for the given Go runtime.GOOS/runtime.GOARCH. It selects, in order of preference, npx, then uvx, then binary — the run-time fetchers first, since they need nothing pre-installed. (Registry entries carry exactly one method in practice; the ordering only matters as a tiebreak.)
- npx → {Command:"npx", Args:["-y", <package>, <distArgs>...]}. The -y flag lets npx self-install the package non-interactively on first run instead of blocking on an install prompt.
- uvx → {Command:"uvx", Args:[<package>, <distArgs>...]}. uvx fetches and runs the package itself; no prompt to suppress.
- binary → the platform's cmd basename becomes Command (contenox does NOT download the archive), with its args/env, and a Note that the user must install the agent and have that binary on PATH. Returns a clear error if no platform entry matches goos/goarch.
Env is always non-nil (empty for npx/uvx that declare no env).
Source Files