Transport Module Guide

Single-line summary: Each transport module verifies its native credentials, normalizes the platform message into NormalizedMessage, applies the configured HistoryPolicy, and dispatches to the agent — all four follow the same shape with protocol-specific verification.

See also: architecture-overview, normalized-message-guide, identity-auth-guide, webfinger-agent-card-guide, deployment-patterns, glossary

Spec sources: docs/spec/{normalized-message,a2a-agent-card,transport-rest-v0.1}.md. Implementations: packages/transport-{activitypub,a2a,email,rest}/.

Universal Adapter Contract

Every transport module follows the same five-step contract:

1. Verify wire credentials. Set sender.auth_method and sender.verified accordingly.
2. Mint IdentityEvidence for what was verified. Attach to sender.identities.
3. Apply HistoryPolicy to the conversation history (oldest-first), trim to the consumer’s budget, attach to message.history.
4. Set recipient_capabilities statically per protocol (the per-protocol value is fixed; see table below).
5. Invoke the agent with the NormalizedMessage + AgentContext.

The agent receives uniform input regardless of the transport — that is the point of the layer.

ActivityPub (@mentionable/transport-activitypub)

Library: Fedify.

A2A (@mentionable/transport-a2a)

Library: @a2a-js/sdk.

Email (@mentionable/transport-email)

Stack: Gmail API for the reference inbound; Postalsys (Nodemailer + smtp-server + ImapFlow + PostalMime) for self-hosted SMTP/IMAP. Outbound DKIM via Nodemailer.

REST (@mentionable/transport-rest)

Built-in. The lightest-weight surface for browser, IDE, script, and Connector clients.

Per-Protocol recipient_capabilities Defaults

import {
  ACTIVITYPUB_RECIPIENT_CAPABILITIES,
  EMAIL_RECIPIENT_CAPABILITIES,
  A2A_RECIPIENT_CAPABILITIES,
  SLACK_RECIPIENT_CAPABILITIES,
} from '@mentionable/core'

Identity Evidence Pipeline (Per Adapter)

native verification ─┐
                     ├──► transport mints IdentityEvidence
                     │     proof.type = 'transport' (in-runtime)
                     │     OR proof.type = 'signed-attestation' (Connector forwarded)
                     ▼
            attach to sender.identities
                     ▼
   ALSO project safe claims.profile → sender.profile (only after full verification)
                     ▼
                 invoke Agent

For forwarded evidence (e.g. Slack Connector → A2A → agent), the receiving adapter applies filterVerifiedForwardedIdentityEvidence:

• Verify signed-attestation proof via ForwardedIdentityEvidenceVerifier.
• Match audience against the receiver’s canonical address.
• Enforce freshness (default: requireExpiresAt, maxAge 600s, maxTtl 600s, clockSkew 60s).
• Drop anything that fails any check — silently, never throwing into agent code.

HistoryPolicy Application

Adapters apply the configured HistoryPolicy BEFORE invoking the agent. Default: createSlidingWindowPolicy with maxTurns: 20, maxTokens: 20_000, keepHead: 1. The policy:

1. Tokenizes each turn (model-aware tokenizer if provided, else len/4).
2. Reserves the first keepHead turns as a stable prefix.
3. Walks the tail newest-first until it would exceed token or turn caps.
4. Enforces role alternation in a single pass.
5. Emits cacheBreakpointAfter so prompt caches stay stable.

The agent does not re-apply HistoryPolicy. The shape of message.history is what the consumer should send to the model.

Adapter Authoring Checklist

• Set sender.auth_method to the correct enum value (or 'none' if unverified).
• Set sender.verified accordingly.
• Mint IdentityEvidence for the verified subject; attach to sender.identities.
• Project claims.profile → sender.profile ONLY after full verification.
• Set recipient_capabilities.mention_relay to the per-protocol constant.
• Trim history via HistoryPolicy (chronological oldest-first).
• Validate emitted parts for PolicyPart membership rules (validatePolicyPart).
• Stash full provider data in raw — never lose information.
• Never throw past the agent boundary; convert errors into NormalizedResponse with status: 'error'.

Common Mistakes

• Authenticating Layer 1 (auth_method) but skipping Layer 2 (identities). The forwarded-attestation case requires both.
• Letting agent code see un-trimmed history. The adapter is responsible.
• Forgetting to set recipient_capabilities.mention_relay. Field is REQUIRED — set { kind: 'none' } if unsure.
• Branching adapter behavior on received_via inside the agent. The adapter already encoded the difference; agents read typed fields.
• Forwarding raw OAuth tokens or DKIM keys via claims. Only safe public-ish facts.