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.
| Field | Value |
|---|---|
| AIP | 43 |
| Title | REGISTRY (registry/v1): handle catalog primitive |
| Status | Review |
| Type | Standards Track |
| Domain | registry.agentproto.sh |
| Requires | AIP-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:
- Storage shape (Map keyed by
id? Array iterated linearly? Trie keyed by slug? hand-rolled per host). - Lookup verbs (
get/find/findByType/findByOwnerdiverge across hosts; consumers can't switch hosts without rewiring). - Capability indexing (every host hard-codes its own
if (provider === "s3" || provider === "gcs") { fuse-bridgeable }decision tree). - 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):
handle.id— present on standalone doctype manifests (per AIP-2).handle.provider— present on STORAGE / SANDBOX handles (the provider value, e.g."local-daemon","s3").handle.slug— present on EXTENSION handles ("acme:deal").- A registry-level
keyBy: (handle: H) => stringselector 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):
| Family | Capability key | Meaning |
|---|---|---|
| STORAGE | bridgeable: boolean | Can the bytes be mounted into a sandbox? |
| STORAGE | transport: "symlink" | "fuse" | "mcp" | "tunnel" | How a sandbox sees the bytes (when bridgeable). |
| STORAGE / SANDBOX | pairsWith: string[] | Backend ids of the other family that compose cleanly. |
| STORAGE / SANDBOX | serverReachable: boolean | Can 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:
-
Directory scan. A registry MAY accept a directory path on construction. Every
<file>.<doctype>.tsfile in the directory is imported, its default export validated as a handle of typeH, and registered. The host sets the file naming convention; the registry doesn't impose one. -
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
capabilityclause MUST carry at least one comparator; several comparators must all hold. A missing capability matches onlyexists: false. idglobs follow AIP-38 §Scope matching:*is a wildcard only as a suffix.- A
selectorclause 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;explainreports it as written. An unregisteredkindis an error at save time. Apart from family clauses, the clause set is closed. - An
orderstring MUST name an order the family declares; anything else is an error at save time. selector_saveMUST refuse to change thefamilyof 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 inexpand(id)(oriditself when it expands to nothing) is a member. It MUST give the same answer asresolve, 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:
- include clauses in their declared order, each contributing matching
handles in registry insertion order; then
idspins in their declared order; the first occurrence of a member keeps its position; - exclude clauses remove members;
orderre-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 declarescheapest,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
revisionin 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):
| verb | input | output |
|---|---|---|
selector_save | a Selector | the 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_list | optional family | selectors |
selector_delete | id, force? | refused while referenced, unless force |
selector_resolve | id | explain(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:
| capability | meaning |
|---|---|
vendor | the model builder (the vendor of a vendor/product id) |
kind | llm, embedding, image, ... |
contextWindow | input context size in tokens |
pricing.inputPer1M, pricing.outputPer1M | public list price in USD |
priceTier | a coarse price band the catalog assigns |
variant | route-identity variant (for example free) |
addedAt | ISO-8601 date the model entered the catalog |
tags | includes price:zero when both list prices are 0 |
Its family clauses and their expansions:
| family clause | expansion |
|---|---|
{ 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:
-
Identity selection is doctype-aware. STORAGE keys on
provider; EXTENSION keys onslug; a handle that's a standalone doctype keys onid. The registry'skeyBydefaults pick the right one without the host wiring it case-by-case. -
Duplicate registration is an error, not silent overwrite. A bare
Map.setlets a seconddefineStorage({ provider: "s3" })silently replace the first; the registry refuses, surfacing the collision at boot. -
Capability lookup is the most useful operation.
Mapexposesget(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 plushas,count,unregister,replace,entriessugar.- Default
keyByresolution 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
- AIP-1 —
agentproto/v1core invariants — handle identity rules. - AIP-56 — DOCTYPE, the
createDoctypemeta-factory — what produces the handles the registry stores. - AIP-29 — CLI.md —
defineCliwhose handles a CLI registry catalogs. - AIP-35 — STORAGE.md —
defineStoragewhose handles a storage registry catalogs. - AIP-36 — SANDBOX.md —
defineSandboxwhose handles a sandbox registry catalogs. - AIP-40 — EXTENSION.md —
defineExtensionwhose handles a workspace-extension registry catalogs. - AIP-38 POLICY and AIP-46 AGENT-SESSIONS:
the consumers of
selector:<id>(informative).
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 →
AIP-42: AGENT (agent/v1): base runnable agent primitive
A markdown + frontmatter format for declaring a runnable agent, composing identity, persona, model, tools, actions, skills, workflows, runner, memory, governance, policy, and routines into a single manifest. Standalone runnable in any AIP-9 OPERATOR-conforming runtime. Body is the system prompt. An operator (AIP-9) is an agent holding a role in an organization: it carries every AGENT field and resolves into an effective AGENT.
AIP-44: ACP (acp/v1): Agent Client Protocol profile
An agentproto profile of the upstream Agent Client Protocol (agentclientprotocol.com) that defines how agentproto operators (AIP-9) participate in ACP — both as clients driving subprocess agents and as servers exposed to ACP-speaking IDEs (Zed, VSCode, JetBrains, Cursor). Pins the upstream protocol revision, layers governance/audit hooks, and standardises operator-binding extensions under metadata.aip44.*.