Relay Protocol Specification

2.1 Initiation (outbound)

When a user on instance A requests a connection to a user on instance B, instance A:

1. Generates a random federationToken (at least 32 bytes of entropy).
2. Stores a local Connection row with status="pending", isFederated=true.
3. POSTs to instance B's /api/federation/connect.

POST https://{peer-instance}/api/federation/connect
Content-Type: application/json

{
  "fromInstanceUrl": "https://dividen.ai",
  "fromInstanceName": "DiviDen",
  "fromUserEmail": "alice@dividen.ai",
  "fromUserName": "Alice",
  "toUserEmail": "bob@fvp.app",
  "federationToken": "<random-secret-at-least-32-bytes>",
  "connectionId": "<local-connection-cuid>"
}

2.2 Acceptance callback (inbound)

When instance B auto-approves (or when user B manually accepts later), B POSTs to A's/api/federation/connect/accept:

POST https://{sender-instance}/api/federation/connect/accept
Content-Type: application/json
X-Federation-Token: <token-from-step-2.1>

{
  "connectionId": "<local-connection-id-on-B>",
  "acceptedByEmail": "bob@fvp.app",
  "acceptedByName": "Bob",
  "instanceUrl": "https://fvp.app"
}

After this callback, both sides have status="active" and may exchange relays.

4.1 Type

4.2 Intent

Intent is the semantic purpose of the relay. Senders SHOULD use one of the known values; receivers MUST tolerate unknown intents by treating them as custom.

4.3 Project invite sub-payload (v2.3.1)

Project invites use intent='introduce' with a structured payload. This allows a receiver that knows about projects to surface it as a real invite (bell count, queue item, dashed avatar on card, Accept/Decline buttons) while still degrading gracefully on a receiver that only understands introduce as a generic contact intro.

{
  "relayType": "request",
  "intent": "introduce",
  "direction": "outbound",
  "status": "delivered",
  "subject": "Invite to \"Q3 Rebrand\"",
  "payload": {
    "kind": "project_invite",
    "inviteId": "cmp_xyz",
    "projectId": "proj_abc",
    "projectName": "Q3 Rebrand",
    "role": "contributor",
    "message": "Optional note from inviter",
    "inviterName": "Jon Bradford"
  }
}

Receivers SHOULD treat payload.kind === 'project_invite' as the canonical invite discriminator and mirror the same record set (ProjectInvite, QueueItem, CommsMessage) locally when ingested. The invite is accepted or declined via PATCH /api/project-invites with{ inviteId, action }.

Senders MUST enforce uniqueness — a duplicate POST /api/projects/[id]/invite returns409 { code: 'ALREADY_INVITED', inviteId }. To deliberately rotate a stale invite, resend with{ force: true } in the body; the old invite + queue item + relay + comms message are cancelled and a fresh set is created. The response surfaces replacedInviteId so downstream listeners can reconcile.

7.1 Request headers

7.2 Request body

7.3 Payload conventions

The payload field is free-form JSON, but DiviDen reserves these underscore-prefixed keys for cross-instance metadata. Receivers MUST preserve them on round-trips.

7.4 Response

Always HTTP 200 on accepted relays. Use fields to signal routing outcomes:

// Normal accept
{
  "success": true,
  "relayId": "clx...",          // receiver's local relay ID (sender stores as peerRelayId)
  "ambient": false,
  "cardId": null,               // populated if task intent → Kanban
  "threadId": "clx...",         // echoed so sender can thread
  "parentRelayId": null,
  "attachmentCount": 0,
  "fallback": false,            // true if toUserEmail had no match, routed to connection owner
  // v2.3.2: scope echo
  "scopeResolved": {            // what the receiver actually persisted
    "teamId": "cm_recv_team_x", // null if no scope resolved or sent
    "projectId": "cm_recv_proj_y"
  },
  "scopeDropped": {             // fields sender sent but receiver couldn't resolve locally
    "teamId": null,             // null means no drop; string means the dropped ID
    "projectId": null
  }
}

// Idempotent duplicate
{ "success": true, "duplicate": true, "relayId": "clx..." }

// Ambient silently filtered by recipient preferences
{ "ok": true, "filtered": true, "reason": "quiet_hours" }

7.5 Processing order (reference implementation)

1. Validate x-federation-token against an active connection. 401/404 on failure.
2. Check FederationConfig.allowInbound. 403 if disabled.
3. Idempotency: if (peerRelayId, connectionId) already exists, return early with duplicate:true.
4. Normalize payload (string → object), clamp attachments to 10.
5. Populate payload._sender with sender identity.
6. Detect ambient via payload._ambient or (intent="share_update" && priority="low").
7. Resolve recipient (toUserEmail → local user; fallback to connection requester).
8. If ambient, run gating (§10) — silently filter on block.
9. Resolve thread + parent via peerRelayId lookup.
10. Create AgentRelay row with status="delivered".
11. If task intent (§13), create Kanban card in leads column.
12. Post a CommsMessage (ambient: low priority auto-read; direct: new).
13. Log activity.
14. Respond 200 with receiver's relayId and threadId.

7.6 Scope resolution (v2.3.2)

When the sender includes teamId and/or projectId on the envelope, the receiver runs a deterministic resolution step. Scope is advisory, not strict — an unresolvable ID never rejects the relay. The receiver simply drops that field and echoes the drop.

1. If teamId is present, look up Team by ID on the local instance. Drop if not found.
2. If projectId is present, look up Project. Drop if not found.
3. If projectId resolved and its project.teamId is set, and the sender did NOT provide a teamId (or we dropped it), inherit project.teamId as the scope team.
4. Persist the resolved values on the new AgentRelay row (teamId, projectId).
5. If the relay creates a KanbanCard, also persist projectId on the card (Kanban is project-scoped only — no teamId on card).
6. Echo scopeResolved + scopeDropped in the 200 response.

Peers that don't implement scope continue to work unchanged — both fields are optional on the wire and omitted fields skip the entire resolution step. A future strictScope: true flag on the connection record will let operators opt in to bounce-on-drop behavior; it is NOT enabled by default.

7.7 Ambient gating with scope (v2.3.2)

The ambient filter table (see §10) now accepts object-form entries in addition to legacy topic strings:

// Legacy: opts-out of all "engineering" topic ambient
ambientFilters: ["engineering"]

// v2.3.2: opts-out only of ambient scoped to project cm_proj_xyz
ambientFilters: [{ topic: "engineering", projectId: "cm_proj_xyz" }]

// v2.3.2: opts-out of any ambient scoped to a specific team
ambientFilters: [{ teamId: "cm_team_abc" }]

When an object-form filter is used, ALL specified fields must match the incoming relay for the filter to trigger. A filter of { topic: "eng", teamId: "X" } only blocks ambient with BOTH topic=eng AND teamId=X — narrower filtering, less bleed.

8.1 Request body

8.2 Sender-side effects

On ack receipt, the sender instance:

1. Updates relay status, responsePayload, resolvedAt.
2. Logs federation_relay_completed activity.
3. Posts a CommsMessage to the operator summarizing the outcome.
4. If the relay was linked to a queue item, advances it to done_today.
5. If a checklist item was linked, flips delegationStatus and completed.
6. Emits a relay.state_changed webhook to local subscribers.

9.1 Pre-push checks (MANDATORY)

1. Load the local relay row.
2. If peerRelayId is already set, OR status is delivered|completed|declined, SKIP the push. This prevents duplicate delivery (§14).
3. Verify the connection is isFederated=true, status="active", and has a federationToken.

9.2 Request

POST https://{peer}/api/federation/relay
Content-Type: application/json
x-federation-token: <connection.federationToken>

{
  "connectionId":  "<sender-local-connection-id>",
  "relayId":       "<sender-local-relay-id>",
  "fromUserEmail": "alice@dividen.ai",
  "fromUserName":  "Alice",
  "toUserEmail":   "bob@fvp.app",
  "type":          "request",
  "intent":        "assign_task",
  "subject":       "Draft the Q2 briefing",
  "priority":      "normal",
  "dueDate":       "2026-04-25T17:00:00Z",
  "threadId":      "<thread-root-id-if-continuing>",
  "parentRelayId": "<parent-sender-relay-id-if-reply>",
  "payload": {
    "description": "Pull the numbers from dashboard and draft 500 words.",
    "_context": "Jon asked about the quarterly rollup in chat",
    "_topic": "briefing"
  },
  "attachments": [
    { "name": "q1.pdf", "url": "https://cdn.example/q1.pdf", "size": 120000, "mimeType": "application/pdf" }
  ],
  "callbackUrl": "https://dividen.ai/api/federation/relay-ack"
}

9.3 Ack handling (on HTTP 200)

1. Parse response JSON. Capture relayId as your peerRelayId.
2. Update local relay: peerRelayId, peerInstanceUrl, status="delivered".
3. Log federation_relay_acked activity.
4. Post an optional low-priority comms confirmation to the sender operator.

9.4 Failure handling

• HTTP 401 / 404: federation token invalid or connection inactive. Mark relay as expired or surface a reconnect prompt to the operator.
• HTTP 403: inbound federation disabled on peer. Same treatment.
• HTTP 5xx / timeout: retry with exponential backoff (suggested: 30s → 2m → 10m → 1h). Keep status as pending during retries.
• Terminal retry cap: after 24h, transition to expired and notify the operator.

10.1 Identification

A relay is ambient if ANY of the following:

• payload._ambient === true (preferred, explicit)
• payload.ambient === true (legacy)
• intent === "share_update" && priority === "low" (implicit)

10.2 Gating (receiver MUST implement)

Before persisting an ambient relay, the receiver checks the recipient's UserProfile preferences. If any gate blocks, return HTTP 200 with { ok: true, filtered: true, reason: "..." } and DO NOT create a record.

10.3 Behavioral contract (RECEIVER AGENT)

The receiving instance's agent MUST follow these rules. DiviDen enforces them via the system prompt; external implementations should encode the equivalent behavior.

1. HOLD silently. Do NOT surface the relay as a notification, banner, or standalone message.
2. Weave on topic-match. When the operator's next message fuzzy-matches payload._topic or payload._context, weave the ambient content into your reply naturally.
3. Attribute the source. Use sender name from payload._sender.name — e.g. "FVP mentioned earlier that the weather is 72°F...".
4. No backend jargon. Never say "I received an ambient relay from...". Translate to conversational English.
5. Respond silently. If the relay needs a reply, fire relay_respond without announcing "I sent a reply".
6. Passive collection. If no topic match surfaces within 24h, the relay stays in the ambient queue until it expires or is dismissed.
7. Never duplicate. Once woven or responded to, mark the relay resolved locally.

10.4 Ambient vs direct — UI surfacing

DiviDen's reference rendering:

11.1 IDs on each side

Thread IDs are sender-assigned but echoed on every relay. The receiver stores the thread ID as-is; parent resolution uses peerRelayId lookup.

Sender sends reply:
{
  "relayId":       "sender-r2",
  "threadId":      "sender-r1",        // root relay id on sender
  "parentRelayId": "sender-r1",        // sender's id of parent
  ...
}

Receiver resolution:
1. Look up local parent: AgentRelay where peerRelayId="sender-r1" AND connectionId=conn
2. If found: parentRelayId = localParent.id, threadId = localParent.threadId || "sender-r1"
3. If not found: threadId = "sender-r1" (best-effort), parentRelayId = null

Receiver persists with its own local IDs; echoes threadId="sender-r1" back in the response
so the sender can confirm continuity.

11.2 Self-thread root

If no parent resolves and no threadId is supplied, the receiver treats the new relay as its own thread root — setting threadId = relay.id.

12.1 Schema

12.2 Location

Attachments can live in body.attachments OR payload.attachments. Receivers MUST accept both and normalize — the reference implementation folds them back into payload.attachmentsfor persistence so round-trips preserve them.

12.3 Comms rendering

DiviDen renders attachments as a markdown list appended to the comms message:

Attachments:
• [q1.pdf](https://cdn.example/q1.pdf) (117 KB)
• [chart.png](https://upload.wikimedia.org/wikipedia/commons/0/06/Communication_Diagram.png) (42 KB)

13.1 Card fields

13.2 Card updates back to sender

If the operator moves the card through their pipeline, the receiver SHOULD push acard-update webhook back to the sender so both boards stay in sync:

POST {sender}/api/federation/card-update
x-federation-token: <connection-token>

{
  "peerCardId":  "<receiver-local-card-id>",  // sender will correlate via CardLink
  "localCardId": "<sender-peer-card-id>",
  "relayId":     "<sender-peer-relay-id>",
  "peerRelayId": "<receiver-local-relay-id>",
  "newStage":    "active",
  "newPriority": "high",
  "title":       "Draft Q2 briefing — in progress",
  "reason":      "pulled in by Bob",
  "fromUserName":  "Bob",
  "fromUserEmail": "bob@fvp.app",
  "timestamp":   "2026-04-18T14:32:00Z"
}

14.1 Receiver-side

// On POST /api/federation/relay
if (body.relayId) {
  const existing = await db.AgentRelay.findFirst({
    where: { peerRelayId: body.relayId, connectionId: conn.id },
  });
  if (existing) {
    // Respond 200, no new record, no side effects.
    return NextResponse.json({
      success: true,
      duplicate: true,
      relayId: existing.id,
    });
  }
}

14.2 Sender-side

// Before pushing, check the local relay state
const local = await db.AgentRelay.findUnique({ where: { id: relayId } });
if (local.peerRelayId ||
    ['delivered','completed','declined'].includes(local.status)) {
  // SKIP — already pushed successfully. DO NOT push again.
  return true;
}

// After successful push (HTTP 200 from peer):
await db.AgentRelay.update({
  where: { id: relayId },
  data: {
    peerRelayId:     ack.relayId,
    peerInstanceUrl: conn.peerInstanceUrl,
    status:          'delivered',  // CRITICAL — without this, re-surfacing causes re-push
  },
});

15.1 Local endpoint

POST /api/relays/{id}/dismiss
{ "reason": "not relevant anymore" }   // optional

// Effects:
// 1. relay.status = 'declined'
// 2. relay.resolvedAt = now
// 3. relay.responsePayload = '(dismissed by operator: {reason})'
// 4. If peerRelayId + peerInstanceUrl: POST to {peer}/api/federation/relay-ack
//    with status='declined' so the other side also resolves.
// 5. Activity log + webhook emitted.

15.2 UI surface

In DiviDen, the dismiss × button lives in the relay footnote rendered by the shared<RelayFootnote/> component. It is visible on both purple (inbound) and green (outbound) cards when the relay is not yet terminal.

Compatibility rules

• Senders MAY send new optional fields. Receivers MUST ignore unknown fields (no strict-parse).
• Unknown intents are treated as custom.
• Unknown statuses on ack are logged but do not fail the request.
• Breaking changes bump the major version; DiviDen will advertise both old and new endpoints in parallel for 90 days.