Glossary
Status: Living terminology. Prefer these terms in new docs and code.
Agent
A callable service addressed as @agent@domain.tld. An Agent implements the
Agent.handle() interface and receives a NormalizedMessage.
Transport
A protocol surface over which an Agent can be reached. Mentionable v0.1 defines ActivityPub, A2A, Email, and REST transports. Transport names are wire-level concepts, not package names.
Use Transport when discussing routing, carriers, wire encodings, authentication channels, or conformance.
Transport Module
A library package that implements a Transport for a Mentionable runtime. The
current repository names these packages @mentionable/transport-*.
Use Transport Module when discussing code that converts between a transport’s native wire format and Mentionable’s normalized model.
Connector
A deployable integration that connects an external product, platform, or client environment to Mentionable agents. A Connector may use one or more Transports to reach agents. For example, the Slack Connector receives Slack events and then calls agents over REST or A2A.
Anyone may build a Connector. Agents and operators decide which Connector instances they trust.
Connector Instance
A concrete deployment of a Connector at a public origin, such as
mentionable-slack.example. Connector instance identity matters because it is
the issuer for Connector-signed attestations and policy-resumption envelopes.
Connector Card
A public discovery document for a Connector Instance. It advertises callback URLs, active signing keys, and previous keys still accepted during rotation.
The current v0.1 compatibility path is /.well-known/adapter-card. New docs
should call the concept Connector Card even while that path remains for wire
compatibility.
Trusted Connector Issuer
A local trust-policy entry saying a receiver is willing to rely on a specific Connector Instance for specific identity methods, assurance classes, and subject namespaces.
Cryptographic validity is necessary but not sufficient: a receiver must also decide whether the issuer is trusted for the claimed method.
Identity Evidence
A transport-neutral envelope for already-verified caller identity. Transport
modules and Connectors produce IdentityEvidence;
Agents apply local policy before relying on it. See identity-auth-guide.
NormalizedMessage
The single contract between adapters and agents. A transport-neutral envelope
carrying id, thread_id, sender, recipient, parts, history,
recipient_capabilities, received_via, received_at, raw, and optional
policy_resolution. See normalized-message-guide and
docs/spec/normalized-message.md.
NormalizedResponse
What Agent.handle() returns (or yields). Carries reply_to, parts,
status: 'ok' | 'partial' | 'error', optional error, optional streaming
(stream_id, seq, final), and optional push_back hint.
HistoryPolicy
Pluggable strategy for trimming a conversation HistoricalMessage[] to a
model’s input budget. Adapters apply it BEFORE invoking the agent. Default is
createSlidingWindowPolicy with stable head + role-alternation enforcement.
See transport-module-guide#historypolicy-application.
PolicyPart
The normalized step-up mechanism for authorization, consent, payment, refusal,
and rate-limit responses. Use PolicyPart when ambient Identity Evidence is not
enough for the requested operation. Seven well-known kinds; the wire kind is
an open string. See policy-part-guide.
PolicyResolution
Verified completion of a prior payment_required or consent_required
PolicyPart. Carried on NormalizedMessage.policy_resolution by the inbound
adapter (Pattern 1 — in-band) or the agent’s own callback endpoint
(Pattern 2 — out-of-band). Agents MUST verify in_reply_to_state against
their own issuance store before acting.
AgentChain
Where this agent sits in a chained multi-agent turn sequence. Carries hop
(1-indexed), max_hops (operator-supplied ceiling), is_final. Set by the
caller when dispatching a relay turn. See multi-agent-composition.
RecipientCapabilities
Required, structured per-recipient platform capabilities on
NormalizedMessage.recipient_capabilities. Carries mention_relay
(inline | recipient-field | addressing | none) and optional agent_chain.
LLM agents read this to decide how to dispatch sibling agents. See
normalized-message-guide#recipient_capabilitiesmention_relay.
Sender Profile
Presentation and attribution facts attached to a Sender, such as display
name, username, profile URL, avatar URL, locale, timezone, provider, and
provider-specific whitelisted extensions.
Sender Profile is context, not authentication. Agents may render it to humans or to an LLM Harness, but authorization, account linking, payment, delegation, and rate-limit decisions must rely on verified identity evidence and local policy.
Profile Claims
Profile facts carried under IdentityEvidence.claims.profile. A receiver may
project them into NormalizedMessage.sender.profile only after the evidence
signature, audience, freshness, and local Trusted Connector Issuer policy pass.
BytesRef
The discriminated union backing file/artifact byte payloads. Three variants:
{ kind: 'inline'; data_base64 }, { kind: 'url'; url; expires_at? }, and
{ kind: 'content_addressed'; algo: 'sha256'; digest; url? }. Lets adapters
choose between embedding bytes, linking remote URLs, or addressing content
by hash.
WebFinger
The discovery hub binding @agent@domain.tld to its ActivityPub actor and
Agent Card. Always served at https://{domain}/.well-known/webfinger, even
when other transports are mounted under a basePath. See
webfinger-agent-card-guide and docs/spec/webfinger.md.
Agent Card
The Mentionable agent’s discovery document, advertised via the WebFinger
https://mentionable.dev/ns/rel/agent-card rel (deprecated alias accepted on
inbound: https://mentionable.dev/agent-card). Carries identity fields, optional
a2a section (endpoint, transport, auth, capabilities), optional
activitypub section, and mentionable.signing_key (Ed25519, load-bearing
for agent-self-sign attestations and PolicyResolution receipts). See
webfinger-agent-card-guide#agent-card-structure.
URL Scheme
The https://mentionable.dev/ namespace convention for machine-dereferenceable
identifiers — extension URIs, JSON-LD context terms, custom WebFinger rels,
tools. Mentionable standardises on /ns/<topic>/v<X.Y> for versioned spec
identifiers (matching the W3C / JSON-LD / ActivityPub /ns/ precedent),
/ns/v<N>#<term> for cross-spec JSON-LD context terms, /ns/rel/<name> for
custom rels, and the root for tools like /trace/. Legacy /spec/* and
/agent-card URIs are recognised on inbound during a transition window but
never emitted outbound. See url-scheme.
LLM Harness
The prompt-building layer inside an LLM-backed Agent. It converts a
NormalizedMessage into model input while preserving trusted runtime facts,
caller identity summaries, participant attribution, conversation history, and
the current request boundary.
The harness is agent-side: Connectors and Transport Modules should preserve
facts in NormalizedMessage; the harness decides how those facts are rendered
for a model. Authorization and policy decisions remain code-side.
Connector-Issued Attestation
An IdentityEvidence entry with proof.type:"signed-attestation" issued by a
Connector Instance. It is portable across origins only when it is audience-bound,
fresh, signed by the Connector key, and accepted by the receiver’s Trusted
Connector Issuer policy.
Channel
A product-specific user surface inside a Connector, such as a Slack workspace, Discord guild, Teams tenant, or email mailbox. Channel identity is not the same as Connector identity.
Invocation-Based Acceptance
A policy pattern where the act of mentioning or calling an Agent counts as acceptance for low-risk terms. The first invocation should still receive transport-appropriate notice: footer for email, DM for ActivityPub, Connector UI for Slack/Teams/Discord, and AgentCard/WebFinger metadata for A2A/REST.
Deprecated: Adapter
Adapter is the old umbrella word that mixed Transport Modules and Connectors.
Do not introduce new normative uses of it. v0.1 compatibility paths, wire
fields, and env names may keep adapter_* spelling until a protocol version
explicitly replaces them.