Internal API: Agent

This is what the Agent and the Bridge actually say to each other today. It's pulled straight from the code: routes/api.php and the controllers on the Agent side, and src/handlers/index.js and src/bridge.js in the Bridge.

Looking for the wishlist of endpoints that don't exist yet? That's External API: Future.

Contents

1. The shape of it
2. Bridge → Agent over HTTP
3. Agent → Bridge over the WebSocket
4. The round trip, one request at a time
5. Things the Bridge sends unprompted
6. Callback payload fields
7. Loose ends

The shape of it

There's no REST API into Foundry. Everything is a message with a type, and it goes round in a loop:

Player's browser ──POST /api/attackroll──▶ Agent
Agent ──GameUpdate { type: ATTACK_ROLL }──▶ Reverb ──▶ Bridge (GM's Foundry)
Bridge runs the roll in Foundry
Bridge ──POST /api/foundry/callback { type: ROLL_RESULT }──▶ Agent
Agent ──FoundryResponse { type: ROLL_RESULT }──▶ Reverb ──▶ Player's browser

A few rules hold for all of it:

• Everyone meets on one channel. Both directions use the private channel cpr-agent.{channel_id}, which is the GM's session.
• The GM's Bridge does the work. Only the GM's Foundry has to be open for the Agent to work. Players' Bridges mostly just link their accounts and share their rolls.
• requestId ties it together. The Agent makes a UUID for each request, and the Bridge sends it back on the reply. That's how a player's browser knows which reply is theirs.
• agent_link says who asked. The Agent adds it to everything it broadcasts, so the Bridge knows which Foundry user a request belongs to.

Bridge → Agent over HTTP

Every call from the Bridge sends the user's API key as Authorization: Bearer <token> (a Sanctum token), except the setup code lookup, which happens before the Bridge has a key.

What the callback does with it

1. Validates the payload (the full list is in Callback payload fields).
2. Works out the user from the Bearer token.
3. Handles a few types specially:
   • LINK_PLAYER_CHARACTER and GM_LINK_PLAYER_CHARACTER link a Foundry user to an Agent account and get a direct JSON answer (with the agent_link). They're not broadcast.
   • If there's an isGM flag, it updates the user's GM status. It'll promote you, but it won't demote you while you own an active session.
   • ACTOR_DATA and SHEET_DELTA get written to the Redis cache straight away, and a queued job saves them to the database. More in The Delta System.
4. Broadcasts everything else to the channel as a FoundryResponse event, and also caches it for 10 seconds under its requestId.

De-duplication. SHEET_DELTA, ACTOR_DATA, both link types, ROLL_RESULT and DICE_ROLL_EVENT get ignored if the same requestId has already come in. The Agent still answers 200 with duplicate_ignored, so Foundry doesn't sit there retrying.

Agent → Bridge over the WebSocket

The Agent talks to Foundry by broadcasting a GameUpdate event on cpr-agent.{channel_id}. The Bridge listens for .GameUpdate, reads its type, and looks up a handler in HANDLERS (src/handlers/index.js). Anything it doesn't recognise gets logged as Unknown DataType and dropped.

On the way out, the Agent tacks on the logged-in user's agent_link and channel_id if they're not already there.

Going the other way, callbacks come back to players' browsers as a FoundryResponse event on the same channel.

The round trip, one request at a time

Every row starts in the player's browser as a call to the Agent's API. Those routes use the normal Laravel session, and need the app to be configured and the profile set up.

Rolls

Every roll comes back as a ROLL_RESULT, with the total, the raw roll, the label and whether it was a crit.

Every roll also carries the rollMode (publicroll, gmroll, blindroll or selfroll), and the Agent uses it to decide who gets to see the result.

Character data

Changing the sheet

Cyberdeck and cyberware

Tokens and the map

Pairing

GET /api/pairing/status is the player's Agent checking on that PAIR_CONFIRMED.

Routes that never reach Foundry

These answer straight from the Agent, no Bridge involved:

Things the Bridge sends unprompted

Not everything is an answer. The Bridge also hooks into Foundry and POSTs these to /api/foundry/callback on its own:

Rolls also get passed to other players' Foundry clients over Foundry's own socket, so they see the little side popup. That part never touches the Agent.

Callback payload fields

Everything the callback accepts. All optional apart from type, and each message only uses the ones it needs.

Loose ends

Stuff I spotted while writing this up, which is worth sorting at some point:

• UPDATE_ACTOR has a handler in the Bridge, but nothing in the Agent sends it anymore.
• DICE_ROLL_EVENT is still listened for on the Agent side and de-duplicated, but the Bridge only ever sends ROLL_RESULT now.
• POST /api/foundry/update is only there for older Bridges. Everything current uses /api/foundry/callback.
• Notes go out as UPDATE_STAT. It works, because notes are just a path, but the name's a bit misleading.