AIP-70: GLOSSARY (glossary/v1): canonical names and vocabulary for every AIP

One name per AIP, used the same way in its title, its schema ids, its package, its define function and its tool names; one meaning per term across the specs and the reference implementation. Fixes the naming rules, the names.json registry and the ratchet check that enforces it, the vocabulary with the senses each term must not take, and the deprecated aliases with their replacements.

FieldValue
AIP70 (provisional, editors assign the final number)
TitleGLOSSARY (glossary/v1)
AuthorJeremy André <[email protected]>
StatusDraft
TypeMeta
RequiresAIP-1, AIP-2
Created2026-10-23
Resourcesspecs/names.json, glossary.json, scripts/check-names.mjs

Abstract

This AIP gives every AIP one name and every recurring term one meaning.

  1. Naming rules: an AIP's name is used, in a fixed form, in its title, its schema ids, its document file, its package, its define function and its tool names.
  2. The registry specs/names.json: the canonical names of every AIP, plus the list of known deviations, checked by scripts/check-names.mjs as a ratchet (a new deviation fails; a fixed one must leave the list).
  3. The vocabulary (glossary.json): each term with its meaning, its owning AIP and the senses it must not take; and the deprecated aliases with their replacements.

Motivation

A snapshot of the corpus and of the reference implementation (2026-10-23) found:

  • an AIP carries up to seven names (title name, title spec name, schema id, package, define function, code SPEC_NAME, tool prefix) and they rarely agree: AIP-11 is LESSON in its title, agentlearning/v1 in its title spec name, learning/v1 in its schema and agentlesson/v1 in code;
  • six title formats, an AIP with no name (66) and one with no AIP-n: prefix (50);
  • packages named after something else than their AIP (51 in redaction, 52 in mastra, 61 in llm-endpoint, 67 in model-intel), and one package carrying five AIPs;
  • about fifteen overloaded terms. The binary a host drives is an "agent CLI" in AIP-45, an adapter in AIP-46 and a harness in code; operator is an agent in AIP-9 and a human in AIP-46; profile, preset, policy and mode each carry five or six meanings.

Every one of these is a place where a reader, a reviewer or an agent picks the wrong meaning. Names drift because nothing checks them. This AIP writes them down once and makes the check mechanical.

Specification

The key words MUST, MUST NOT, SHOULD, and MAY are to be interpreted as described in AIP-1.

1. Naming rules

Every AIP has a NAME: uppercase ASCII words joined by - (POLICY, MODEL-ROUTING, CLOUD-AGENT). Singular, unless the document is inherently a set (SECRETS). From the NAME, with name its lowercase form:

artefactformexample
titleAIP-<n>: <NAME> (<name>/v<N>): <summary>; process AIPs without a spec id: AIP-<n>: <NAME>: <summary>AIP-38: POLICY (policy/v1): composable access policy
spec id<name>/v<N>, N the major version of the AIPwork/v2
document schema ids (schema: and JSON Schema const)<name>/v<N>, or <name>.<kind>/v<N> (one level) when the AIP defines several documentsknowledge.entry/v1
document file, when the AIP defines one<NAME>.md; an AIP defining several documents names each <KIND>.md and lists them as filesPOLICY.md; AIP-68: STEWARD.md, SECRETARY.md
package@agentproto/<name>; driver family: @agentproto/driver-<name>; coordination family: @agentproto/agent-<name>@agentproto/policy
define functiondefine<Name> in PascalCasedefinePolicy
tools<name>_<verb> (or a documented sub-resource, <name>_<resource>_<verb>)session_restart
layerone of process, primitives, capabilities, identity, coordination, memory, surfaces, drivers, host
  • Coordination packages MAY carry the agent- prefix (@agentproto/agent-<name>), as the AIP-48 kernel does with @agentproto/agent-runtime.
  • The agent prefix is not used in names, spec ids or schema ids. The schema ids already in use mostly lack it (policy/v1, role/v1, agent/v1); titles and code that carry it (agentpolicy/v1) are deviations.
  • The host layer holds the AIPs of a machine that runs agents: sessions, runs, sentinels, inference endpoints, decisions, cloud agents, quota and auth profiles.
  • An external standard MAY fix a document file name (AIP-50 follows the auth.md standard); the AIP NAME then follows the file (AUTH).
  • A superseded AIP keeps its number and its registered name. It is exempt from the uniqueness rule (its successor carries the name forward) and from the package and layer checks.

2. The registry and the check

specs/names.json lists, for every AIP: aip, name, specId, file or files, package, define, layer, supersededBy. It describes the target, not the current state. Its pending array lists the deviations that exist today, by id (aip-38:title, aip-46:package, aip-34:schema:presence).

scripts/check-names.mjs (CI, blocking):

  • fails on a registry error: a spec without an entry, an entry without a spec, a duplicate active name or spec id, an unknown layer, an entry whose own fields break section 1 (name format, specId, define, package, file or files), a glossary term or alias missing from the tables of this AIP;
  • computes the deviations: title, superseded status, package, layer, and every schema id (JSON "const" or a schema: line) in the AIP's own text and in any file under resources/aip-<n>/, keyed by the file it appears in, so fixing one occurrence cannot hide another;
  • fails on a deviation absent from pending (new drift), and on a pending id that no longer deviates (fixed: it must leave the list, so it cannot return);
  • reports the deprecated aliases of section 4 per spec, without failing.

A new AIP MUST add its entry to names.json in the PR that adds it, and MUST NOT add itself to pending.

Implementations SHOULD run the same comparison on their side: a package's name, its SPEC_NAME (or equivalent) and its tool prefixes against the registry. For the reference implementation this is a check in agentproto/ts, reading names.json from the canonical specs checkout its CI already uses.

3. Vocabulary

One meaning per term. The owning AIP defines the term; every other AIP uses it in that meaning only. The machine-readable form is glossary.json; this table renders it.

termmeansownernever means
harnessan agent binary driven by a host (Claude Code, OpenCode, Codex, Hermes) and its manifestAIP-70, then AIP-45 (the AIP-45 rename (P1))a bridge into a foreign framework; a session preset
bridgethe projection of an agentproto handle into a foreign framework (Mastra, AI SDK)AIP-70, then AIP-52 (the AIP-52 rename (P1))the agent binary
driveran inward bridge from agentproto to an external API, CLI, MCP server or SDKAIP-30a harness
operatoran agent holding a role in an organizationAIP-9the human who controls a host (say user); the principal holding a host's credential (say host operator); the host user's name for a session (say operator label); a runtime strategy (the shared in-process shell is the behaviour of runtime.kind: in-process)
userthe human who owns and controls a host and its sessionsAIP-70an AIP-9 operator
host operatorthe principal that holds a host's own credential: the user, or a client acting for them (for example a command line or a desktop app); written "the operator" inside AIP-46 and AIP-71, where no AIP-9 operator appearsAIP-70, then AIP-46 (an AIP-46 amendment)an AIP-9 operator
principalthe identity-ref a grant names and a request resolves to (a host operator, a session, anonymous, an AIP-9 operator, a user)AIP-38an AIP-23 identity workspace
sessionone running (or ended) harness invocation managed by a hostAIP-46a terminal, a browser instance, an ACP wire session (say "ACP session")
labelfree text attached for display to a session, a spawn request or an auth profile; a grant never matches itAIP-46an operator label; the label: scope form, which matches the operator label
operator labelthe durable name only the host operator, or the host itself, assigns to a session or a lineage, matched by label: scopes and session-label:// principalsAIP-46a label; a session id; an AIP-9 operator, or its slug
context settingsthe contextSettings block of a session: the context floor, the absolute compaction threshold and the reservation of compaction to the operator, each layered as its own axisAIP-46the contextProfile axis of a session config; a prompt's context window
session confighow a session runs: harness, model, effort, posture, context, route, auth profile, retry, fallbackAIP-70, then AIP-46 (agentproto/agentproto#89)a permission
session preseta named, saved session configAIP-70, then AIP-46 (agentproto/agentproto#89)a gateway; a harness manifest; a per-harness default overlay (say harness defaults, the host layer of AIP-46 §Layers)
gatewaya backend endpoint a harness can be pointed at (Anthropic-compatible, OpenAI-compatible)AIP-45a preset
auth profilea named reference to the credential a session bills or authenticates throughAIP-70, then AIP-69 (agentproto/agentproto#87)a context setting; a browser identity; a daemon config overlay (say config profile)
vendorthe builder of a model (the vendor in a vendor/product model id)AIP-70, then AIP-43 (agentproto/agentproto#90)who bills
vendor extensiona namespaced key (metadata.<vendor>) a file carries for one host, which the spec does not define and which other hosts MUST tolerateAIP-70a model vendor (say vendor); a field the owning AIP defines
endpointthe party that serves and bills a modelAIP-70, then AIP-69 (agentproto/agentproto#87)the model builder; an inference endpoint (AIP-61, always qualified); a gateway; an HTTP route
routethe billing path a model is reached through (an @<route> suffix on a model id)AIP-70, then AIP-43 (agentproto/agentproto#90)an AIP-57 resolution target
policyan AIP-38 access document: grants, limits, requirementsAIP-38a completion check, a retry rule, settings, a drive or model allow list (say grant)
gatea check that passes or fails at a boundary: the delegation spawn gate of AIP-46, a completion check, a review verdictAIP-70, until the AIP-46 split (SESSION)a policy
posturewhat a session may do without asking (plan, accept-edits, bypass, read-only)AIP-70, then AIP-46 (agentproto/agentproto#89)a harness mode
modea harness-native, mutually exclusive operation profile declared in an AIP-45 manifestAIP-45posture; a session lifetime; how a session is billed (billing basis); an action
rolean AIP-47 organizational role (intent, never permission)AIP-47an access role; a position; a model slot
access rolea permission tier of a human or agent inside a host's organization (owner, admin, editor, viewer), evaluated by AIP-38 policyAIP-47an AIP-47 role; a session's delegation authority, which is its bound agent's delegates_to (AIP-46 §Delegation)
positiona seat in an organization that one operator holds at a timeAIP-47a role
delegation profilea host-local file that names a profile (harness, model, prompt) for a delegated session; the daemon's own roles directory holds themAIP-70an AIP-47 role; an access role
model slota logical model name resolved per host (review.small, judge.session)AIP-70, then AIP-57 (an AIP-57 amendment)an AIP-47 role
selectora saved, ordered, declarative selection over a registry familyAIP-70, then AIP-43 (agentproto/agentproto#90)a function predicate
registrythe in-memory catalog of handles of one familyAIP-43a data catalog
catalogthe data a family's registry serves (model prices, context sizes)AIP-70, then AIP-43 (agentproto/agentproto#90)the registry primitive
packan AIP-64 installable capability bundleAIP-64an AIP-57 routing table; a host-local bundle of imported MCP servers and skills (say bundle)
routing tablean AIP-57 map from a keyspace to targetsAIP-57a pack
runtimethe AIP-48 multi-agent execution kernelAIP-48the host daemon
hostthe daemon that runs sessions, runs and their state on a machineAIP-70a model endpoint
workspacean AIP-34 workspace node, including the x.workspace doctypesAIP-34a run's scratch directory
node scopethe nearest declared AIP-34 node whose folder contains a session's AIP-46 ground; walls, policy and memory visibility apply to itAIP-70, then AIP-34 (an AIP-34 amendment)an operator's home (operators are not scoped, sessions are); a policy scope string
run directorythe scratch directory a run getsAIP-70, then AIP-58 (an AIP-58 amendment)a workspace
terminala PTY process driven through a hostAIP-70, until a TERMINAL AIPa session; the end state of a lifecycle (say "end state")
browser instanceone running browser driven through AIP-63AIP-63a session
browser identitya saved browser login stateAIP-70, then AIP-63 (an AIP-63 amendment)an auth profile

A term whose owner column reads "AIP-70, then AIP-n" is owned by this AIP until AIP-n (or the named change) defines it; the row then moves to that owner. user and host are owned by this AIP until an AIP defines them.

4. Deprecated aliases

aliasuse
agent CLIharness
adapter slugharness slug
adapterSlugharness
agent_start.adapteragent_start.harness
--adapter--harness
human operatoruser
gateway presetgateway
completion policygate
session policysession settings
context profilecontext (session config axis)
decision profiledecision tier
browser profilebrowser identity
model rolemodel slot
model providervendor (builder) or endpoint (billing)
per-run workspacerun directory
terminal sessionterminal
billing modebilling basis
session.modesession.lifetime
harness presetharness defaults (the host layer of AIP-46 §Layers), or a session preset with defaultFor
spawn roleagent (a built-in AIP-42 agent named by agent)

An alias stays readable during the transition. New text MUST use the replacement. A deprecated field, tool or flag name is removed in the next breaking release of the reference implementation; it is not kept past that release. Until then an implementation MAY accept the old name as an alias that behaves exactly like its replacement, and SHOULD warn, naming the replacement and the release that removes it, each time the old name is used. A spec does not carry the old name: the AIP that owned it drops it in the same change that adds the row here.

The rows adapterSlug, agent_start.adapter and --adapter are the agent-CLI sense of adapter (AIP-46's Session field and agent_start input, and the CLI flag). The same adapter key in a WORKFLOW agent step (AIP-15 §Open questions 6) is renamed once that question is settled; adapter in the other senses (AIP-52's FrameworkAdapter and ServiceAdapter, the ADAPTER.md guides) is not deprecated.

5. Changing a name or a term

A new term, a new meaning or a rename is a change to this AIP first: the glossary row (and names.json entry) lands in the same PR as the spec text that uses it. A term used in two AIPs with two meanings is a defect of the corpus, fixed by renaming one of them here.

Rationale

Why a registry and a ratchet, not a big-bang rename. About a hundred deviations exist today. Fixing them in one PR would mix renames that need review (a package split) with trivial ones (a title). The ratchet freezes the drift at today's level, lets each fix land on its own, and makes every fix permanent.

Why drop the agent prefix. The validated schema ids already lack it; the prefix only lived in titles and in some code constants, where it made agentagent/v1 and agentagencies/v2.

Why harness. It is the name the reference implementation converged on (descriptor field, tools, presets), it has no other meaning in the corpus, and it frees adapter and driver, which each had a second sense.

Backwards Compatibility

This AIP changes no wire format. The renames it calls for land as separate PRs (titles and schema ids in the specs, then packages, constants, fields and tools in implementations), each removing its ids from pending. A renamed schema id or tool keeps its old spelling as an accepted alias in the reference implementation until its next breaking release, which removes it (§4).

Security Considerations

None directly. Ambiguous vocabulary has caused security mistakes in this corpus before (AIP-47 had to separate role from access role so that a job title never grants access); keeping one meaning per term is a precondition for reviewing policy text correctly.

Reference Implementation

specs/names.json, specs/resources/aip-70/draft/glossary.json, scripts/check-names.mjs and its self-test scripts/self-test-names.mjs in this repository.

Open Questions

  1. Tool names of sub-resources: session_artifact_add (resource, then sub-resource, then verb) is allowed by section 1; deeper nesting is not, like schema kinds (one level).
  2. Packages that implement several AIPs of one family (the auth provider and auth profile code share @agentproto/auth today): split, or allow a declared family package.

See also

  • AIP-1: process
  • AIP-2: the template whose title convention this replaces

Resources

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