AIP-43: REGISTRY (registry/v1): handle catalog primitive

A primitive that catalogs N defineX'd doctype handles for runtime lookup. Operations (register / get / list / lookup), identity rules, capability metadata namespace, discovery hooks. Hosts use it to assemble per-host provider/backend/tool catalogs without re-implementing the registry shape; the same primitive works for any doctype family.

FieldValue
AIP43
TitleREGISTRY (registry/v1): handle catalog primitive
StatusReview
TypeStandards Track
Domainregistry.agentproto.sh
RequiresAIP-1, AIP-2
Reference Impl@agentproto/registry

Abstract

agentregistry/v1 is a runtime primitive — a generic catalog that collects N defineX-produced doctype handles and exposes a uniform lookup surface so hosts can assemble per-host provider/backend/tool catalogs without re-implementing registry plumbing per doctype family.

The primitive is type-parametric over a doctype handle (StorageHandle, SandboxHandle, OperatorHandle, ToolHandle, …) and exposes four operations: register, get, list, lookup. It also names a capability metadata namespace (handle.capabilities) that hosts populate so cross-handle queries — "every storage backend that supports FUSE-bridging", "every sandbox that pairs with local-daemon storage" — are declarative rather than hard-coded in switch statements.

This AIP defines the rules. The reference implementation lives in @agentproto/registry and is the canonical answer for hosts that don't need bespoke storage semantics.

Motivation

defineStorage (AIP-35), defineSandbox (AIP-36), defineCli (AIP-29), defineOperator (AIP-42), defineExtension (AIP-40) all produce handles — frozen, validated objects describing one instance of a doctype. The per-author API is solved.

What's missing is the catalog side: every host that consumes more than one handle of a given family ends up writing a registry for it, each with its own:

  1. Storage shape (Map keyed by id? Array iterated linearly? Trie keyed by slug? hand-rolled per host).
  2. Lookup verbs (get / find / findByType / findByOwner diverge across hosts; consumers can't switch hosts without rewiring).
  3. Capability indexing (every host hard-codes its own if (provider === "s3" || provider === "gcs") { fuse-bridgeable } decision tree).
  4. Discovery hooks (workspace-local doctypes via EXTENSION.md, provider files in a directory, MCP-published catalogs — none standardized).

The cost compounds: a doctype family ships with defineX, multiple hosts each rewrite the registry plumbing, the registry shape drifts between hosts, capability metadata becomes load-bearing in some hosts and absent in others, and discovery (the most valuable cross-host property — "give me every storage backend the host knows about") is ad-hoc.

agentregistry/v1 factors the registry side out the same way AIP-1 factored doctype identity: one shape, one set of verbs, one capability namespace, valid across every doctype family.

The companion observation: defineX already returns a createDoctype-built handle (AIP-56). The registry doesn't need to know which doctype it's storing — it operates on the universal handle shape (id, frozen body, optional capabilities) and yields the handle back unchanged. One impl, every doctype family.

Specification

A conforming registry is an in-memory catalog with the operations, identity rules, capability metadata namespace, and discovery hooks defined below. The @agentproto/registry reference implementation satisfies all of them; alternative implementations (a host that persists handles to disk or fetches them from an HTTP catalog) MUST satisfy the same observable contract.

Identity

A registry is parameterised by a doctype handle type H. Every entry has a string id derived from one of (in priority order):

  1. handle.id — present on standalone doctype manifests (per AIP-2).
  2. handle.provider — present on STORAGE / SANDBOX handles (the provider value, e.g. "local-daemon", "s3").
  3. handle.slug — present on EXTENSION handles ("acme:deal").
  4. A registry-level keyBy: (handle: H) => string selector when none of the above apply.

Registries MUST refuse register(...) calls whose handle's id is already present — the second registration is an error, not a silent overwrite. Hosts that need replacement MUST call unregister(id) first.

Operations

The minimum surface is four verbs. A reference signature in TypeScript:

interface Registry<H> {
  /** Add a handle. Throws if `keyBy(handle)` is already present. */
  register(handle: H): void

  /** Get the handle by id. Returns undefined if absent. */
  get(id: string): H | undefined

  /** Every handle currently registered, insertion-ordered. */
  list(): readonly H[]

  /** Every handle matching `predicate`. */
  lookup(predicate: (handle: H) => boolean): readonly H[]
}

Hosts MAY extend the surface with sugar (has, count, unregister, replace, entries) but MUST NOT remove or rename the four core verbs.

Capability metadata namespace

A handle MAY carry a capabilities field — a free-form Record<string, unknown>. The registry treats it as opaque (no validation, no normalisation) but indexes it lazily for lookup.

Capabilities are declarative metadata, not behaviour. A storage handle whose capabilities.bridgeable === true is asserting that the backing store can be FUSE-mounted into a sandbox; the registry doesn't verify the claim. Hosts use capabilities for cross-handle queries ("every storage backend whose capabilities.transport is 'fuse'") that would otherwise become hard-coded switch statements.

Suggested namespacing convention (NOT mandated):

FamilyCapability keyMeaning
STORAGEbridgeable: booleanCan the bytes be mounted into a sandbox?
STORAGEtransport: "symlink" | "fuse" | "mcp" | "tunnel"How a sandbox sees the bytes (when bridgeable).
STORAGE / SANDBOXpairsWith: string[]Backend ids of the other family that compose cleanly.
STORAGE / SANDBOXserverReachable: booleanCan a remote host reach this backend (false for local-ide/local-daemon on loopback)?

Hosts SHOULD agree on convention names within a family but the registry itself only relies on the field being a JSON value.

Discovery hooks

A registry is hand-populated by default — hosts call register(handle) for each handle they want to expose. Two optional discovery hooks:

  1. Directory scan. A registry MAY accept a directory path on construction. Every <file>.<doctype>.ts file in the directory is imported, its default export validated as a handle of type H, and registered. The host sets the file naming convention; the registry doesn't impose one.

  2. MCP listing. A registry MAY publish a list_<doctype> tool to an MCP server (per AIP-5 conventions); the tool returns { id, label?, description?, capabilities? } per entry. This lets agents and external tooling enumerate the catalog without import access.

Discovery is OPTIONAL. A registry that only supports register() is fully conforming.

Equality and lifetime

Handles registered into a registry are immutable. The registry MUST NOT mutate the handle body; consumers MUST NOT mutate it after registration (the createDoctype Object.freeze invariant from AIP-56 makes this runtime-enforced for compliant handles).

The registry's lifetime is the host process. Persistence across restarts (e.g. registries hydrated from a config file at boot) is the host's concern — the registry primitive itself is in-memory.

Reference signature

import { createRegistry } from "@agentproto/registry"

const storageRegistry = createRegistry<StorageHandle>({
  family: "storage",
  keyBy: (handle) => handle.provider,
})

storageRegistry.register(localDaemonStorage)   // defineStorage(...) result
storageRegistry.register(s3Storage)
storageRegistry.list()                          // readonly StorageHandle[]
storageRegistry.get("local-daemon")             // StorageHandle | undefined
storageRegistry.lookup(h => h.capabilities?.bridgeable === true)

The family field is informational (used in error messages, MCP tool names if discovery is enabled). keyBy is required when the handle type doesn't expose a recognisable id field; createDoctype-built handles default to the rules in Identity.

Saved selectors (added 2026-10-23)

Draft AIP-43 amendment (2026-10-23). Normative identifiers (field names, literals, tool names) are English and final.

Problem. lookup(predicate) takes a function. A function cannot be saved by a user, sent over MCP, referenced from a policy, or shown in a picker. Hosts that needed a named, reusable selection ("every model priced at zero", "these three models in this order", "every tool that writes to the network") each invented a private format: the reference implementation has one for models only, and the older code paths it replaced each hard-coded their own predicate (an id suffix check, a literal list). AIP-38 grants (scope: "selector:<id>") and AIP-46 session configs (model: "selector:<id>") now reference selectors by id, so the format needs one definition.

A saved selector is the declarative, serializable form of lookup: a named, ordered selection over one registry family, stored by the host as user data.

The Selector document

JSON Schema: resources/aip-43/draft/Selector.schema.json.

interface Selector {
  /** Unique on the host across all families: /^[a-z0-9][a-z0-9-]{0,62}$/ */
  id: string
  /** The registry family it selects from: "model", "tool", "skill", ...
   *  Fixed for the life of the id. */
  family: string
  label?: string
  /** Handles matching ANY clause are selected. */
  include?: Clause[]
  /** Handles matching ANY clause are removed. Wins over include and ids. */
  exclude?: Clause[]
  /** Explicit pins (see Identity). A pin need not be registered. */
  ids?: string[]
  /** Default "listed". */
  order?: "listed" | { by: string; direction?: "asc" | "desc" } | string
  /** How a consumer that uses one member at a time picks the next one.
   *  Default "priority". */
  rotation?: "priority" | "round-robin" | "least-recently-limited"
  /** Content digest of this revision, set by the host on save. */
  revision?: string
}

type Clause =
  | { id: string }                       // an id, or a `*`-suffix glob
  | { tag: string }                      // member of capabilities.tags
  | { capability: string                 // dot path into capabilities;
      eq?: unknown; in?: unknown[]       //   at least one comparator
      lte?: number; gte?: number; exists?: boolean }
  | { selector: string }                 // members of another selector
  | { all: Clause[] }                    // conjunction
  | { kind: string; [k: string]: unknown }  // a family clause (below)
  • A capability clause MUST carry at least one comparator; several comparators must all hold. A missing capability matches only exists: false.
  • id globs follow AIP-38 §Scope matching: * is a wildcard only as a suffix.
  • A selector clause MUST name a selector of the same family. A cycle, an unknown selector, or a family mismatch is an error at save time.
  • Family clauses. A family MAY register clause kinds ({ kind, ... }) whose meaning is defined by an expansion into the generic clauses above. A host stores a family clause as written; explain reports it as written. An unregistered kind is an error at save time. Apart from family clauses, the clause set is closed.
  • An order string MUST name an order the family declares; anything else is an error at save time.
  • selector_save MUST refuse to change the family of an existing id.

Identity

A family MAY declare an expansion expand(id) → canonical ids: the registered ids a spelling denotes (alias resolution, a route suffix such as @openrouter stripped, a bare id denoting every registered id whose last segment it is). Expansion is one-way and deterministic. Members are kept as canonical ids; a pin that expands to nothing is kept as written.

  • has(selectorId, id) is true when any id in expand(id) (or id itself when it expands to nothing) is a member. It MUST give the same answer as resolve, and SHOULD be answerable without expanding the whole selector.
  • An exclude removes a member when the member, or any id its subject expands to, matches. A model excluded by its canonical id therefore stays excluded when addressed through an alias or a route suffix.
  • Capability, tag and family clauses cannot match an id that no registered handle carries. An unregistered pin is removed only by an { id } exclude that matches it, or by a { selector } exclude whose members include it.

Resolution and order

resolve(selectorId) returns an ordered, de-duplicated list of ids:

  1. include clauses in their declared order, each contributing matching handles in registry insertion order; then ids pins in their declared order; the first occurrence of a member keeps its position;
  2. exclude clauses remove members;
  3. order re-sorts: "listed" keeps step 1's order; { by, direction } sorts on a capability path (default ascending; members missing the capability sort last; ties keep step 1's order); a string names an order the family declares (the model family declares cheapest, largest-context, newest).

explain(selectorId) returns, for each member, the clause or pin that included it.

A resolution reflects the registry and the selector at the moment it is computed. Consumers decide when they resolve, and their AIP says so:

  • a policy check (AIP-38) resolves at evaluation time;
  • a session (AIP-46) resolves when it binds a model (spawn, restart, handoff, a fallback step) and records the concrete member it chose. Editing a selector never changes the model of a running session by itself.

Selectors are grant-side and config-side only. A request always names a concrete id. A consumer that holds selector:<id> (a session config) resolves it, evaluates each candidate member as a concrete id (policy, eligibility), and uses and records the first one that passes. A host MUST NOT pass the literal selector:<id> as the requested scope of an action.

rotation tells such a consumer how to pick the next member when the current one fails: priority takes the next member in order; round-robin continues after the member used last by any consumer of that selector on the host; least-recently-limited prefers the member whose most recent rate or quota limit, for the account in use, is oldest (members never limited first).

Selectors referenced by policy

A selector named in an AIP-38 grant is part of that grant's meaning: adding a member widens every grant that allows it, and narrows every grant that denies it.

  • Saving or deleting a selector that any AIP-38 policy references is a policy change: the host MUST require the authority it requires to edit that policy, and MUST record it as a governance event (AIP-7) with the old and new revision.
  • An AIP-38 decision that matched through a selector SHOULD record the selector id and revision in its decision record.
  • A host MAY lock a seed that one of its built-in policies references: a locked seed can be copied, not edited or deleted.

Storage, seeds and surface

Selectors are host configuration owned by the user, stored outside any workspace or repository. The registry primitive stays in-memory; the selector store is the host's.

  • A host MAY ship seed selectors (for example zero-cost: the model family members whose input and output list prices are both 0). An unlocked seed is ordinary data: the user can edit it, and the host MUST NOT re-impose its default over a user edit.
  • Deleting a selector MUST be refused while another selector, a session preset, a live session's config or a policy known to the host references it, unless forced. A reference that no longer resolves is an error, and each consumer's AIP defines the outcome (AIP-38: deny; AIP-46: the spawn is refused, a fallback step is skipped).
  • Surface (MCP, with HTTP and CLI mirrors):
verbinputoutput
selector_savea Selectorthe stored selector with its new revision; refuses a cycle, an unknown or cross-family selector clause, an unregistered family clause or order, a family change, an invalid id
selector_listoptional familyselectors
selector_deleteid, force?refused while referenced, unless force
selector_resolveidexplain(id): members in order, each with the clause or pin that included it

A host MAY expose family-scoped aliases of these verbs (for example model_list_save for family: "model"); they MUST behave as the generic verb with the family fixed.

Model family conventions

The model family is the registry consumers reference most (AIP-38 model:invoke scopes, AIP-46 model). Its handles SHOULD carry these capabilities so selectors stay portable across hosts:

capabilitymeaning
vendorthe model builder (the vendor of a vendor/product id)
kindllm, embedding, image, ...
contextWindowinput context size in tokens
pricing.inputPer1M, pricing.outputPer1Mpublic list price in USD
priceTiera coarse price band the catalog assigns
variantroute-identity variant (for example free)
addedAtISO-8601 date the model entered the catalog
tagsincludes price:zero when both list prices are 0

Its family clauses and their expansions:

family clauseexpansion
{ kind: "model", value }{ id: value }
{ kind: "tag", value }{ tag: value }
{ kind: "provider", value }{ capability: "vendor", eq: value } (provider is a legacy alias of vendor, the reference implementation's name for the builder)
{ kind: "priceTier" | "kind" | "variant", value }{ capability: <that name>, eq: value }
{ kind: "price", maxInPer1M?, maxOutPer1M? }{ all: [ { capability: "pricing.inputPer1M", lte: maxInPer1M }, { capability: "pricing.outputPer1M", lte: maxOutPer1M } ] }, keeping only the bounds given; with no bound, { capability: "pricing.inputPer1M", exists: true }
{ kind: "context", min }{ capability: "contextWindow", gte: min }
{ kind: "list", id }{ selector: id }

Price is catalog data like any other capability. A selector such as zero-cost is where a user, or a host's built-in policy, names "free models"; no host code tests prices to decide what a session may use.

Why not just use a Map?

Three reasons:

  1. Identity selection is doctype-aware. STORAGE keys on provider; EXTENSION keys on slug; a handle that's a standalone doctype keys on id. The registry's keyBy defaults pick the right one without the host wiring it case-by-case.

  2. Duplicate registration is an error, not silent overwrite. A bare Map.set lets a second defineStorage({ provider: "s3" }) silently replace the first; the registry refuses, surfacing the collision at boot.

  3. Capability lookup is the most useful operation. Map exposes get(key) cheaply; lookup(predicate) is what hosts actually need ("every storage that pairs with sandbox X"). Standardising the verb keeps capability metadata normative across hosts.

Backward compatibility

This AIP introduces no breaking changes. Existing hand-rolled host registries remain functional — adopting @agentproto/registry is a voluntary refactor. Handles produced by defineStorage / defineSandbox / defineExtension / defineOperator are already in the shape the registry expects (the universal createDoctype handle), so adoption is one register(handle) call per existing handle.

The 2026-10-23 saved-selectors amendment (draft)

§Saved selectors is additive. register, get, list and lookup are unchanged, and a host with no selector store is fully conforming for every consumer that does not reference selector:<id>. A consumer that does reference one (an AIP-38 scope, an AIP-46 model) on a host without selectors gets a resolution error, which AIP-38 treats as a deny.

The reference implementation's model lists (ModelList, model_list_* tools, ~/.agentproto/model-lists.json) are saved selectors of family: "model", and their selector kinds (model, tag, provider, priceTier, kind, variant, price, context, list) are the model family clauses of §Model family conventions, stored as written. Two behaviours move: the zero-cost seed, which the implementation restores on every load, becomes a locked seed (same effect, now declared), and edits of a selector referenced by a policy become audited policy changes.

Reference implementation

The canonical implementation is @agentproto/registry. It implements:

  • createRegistry<H>(options) returning the four-verb surface plus has, count, unregister, replace, entries sugar.
  • Default keyBy resolution per Identity.
  • Optional directory-scan discovery hook (Node-only; uses dynamic import() so it's tree-shakable).
  • Optional MCP-tool discovery hook (depends on @modelcontextprotocol/sdk; feature-gated so non-MCP hosts don't pull the SDK).

Tests cover: identity selection priority, duplicate-registration refusal, capability-lookup correctness, discovery-hook idempotency.

See also

Resources

Supporting artifacts for AIP-43. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →