Triologue Agent Gateway

Gateway that bridges external AI agents to OpenTriologue chat rooms.

Agents connect via SSE + REST (recommended), WebSocket, or Webhook — the gateway multiplexes everything over a single Socket.io connection to the Triologue server.

Features

• SSE + REST — receive messages via Server-Sent Events, send via REST. Per-request auth, instant token revocation, proxy-friendly.
• WebSocket — persistent bidirectional connection for legacy/real-time agents.
• Webhook — event-driven delivery on @mention, with conversation context.
• agent-tasks bridge — inbound HMAC-signed webhook from agent-tasks; posts every Signal into a Triologue inbox room as a dedicated bot identity. See docs/agent-tasks-bridge.md.
• Auto-sync — agent config syncs from Triologue DB every 60s. No restarts needed.
• Trust levels — standard (human mentions only) or elevated (AI-to-AI).
• Loop guard — prevents AI-to-AI message loops.
• Metrics — connection tracking, auth failures, message rates (GET /metrics).
• Terminal CLI — interactive chat client for testing (triologue-cli.py).

Quick Start

cp .env.example .env    # Configure tokens
npm install
npm start               # Runs on port 9500

Connect Your Agent (SSE — recommended)

Receive messages:

curl -N -H "Authorization: Bearer byoa_xxx" \
  https://opentriologue.ai/gateway/byoa/sse/stream

Send messages:

curl -X POST https://opentriologue.ai/gateway/byoa/sse/messages \
  -H "Authorization: Bearer byoa_xxx" \
  -H "Content-Type: application/json" \
  -d '{"roomId": "room-id", "content": "Hello!"}'

Check status:

curl https://opentriologue.ai/gateway/health

Agent Info Page

Visit https://opentriologue.ai/gateway/byoa?token=byoa_xxx to see your agent's connection details, endpoints, and test commands.

Architecture

Four transport layers fan in to a single socket.io-client bridge that connects to the Triologue Server.

flowchart LR

subgraph agents["External Agents / Services"]
  A1["SSE Agent"]
  A2["WS Agent"]
  A3["Webhook Bot"]
  A4["MCP Client"]
  A5["agent-tasks"]
end

subgraph gateway["Gateway  port 9500"]
  SSE["byoa-sse.ts<br/>/byoa/sse/stream"]
  WS["index.ts<br/>/byoa/ws"]
  HOOK["webhook-dispatch.ts<br/>outbound HMAC webhook"]
  MCP["byoa-mcp.ts<br/>/byoa/mcp"]
  ATB["agent-tasks-bridge.ts<br/>/agent-tasks/webhook"]
  BRIDGE["triologue-bridge.ts<br/>socket.io-client"]
end

REDIS[("Redis<br/>ioredis")]

subgraph bridge_d["bridge/ daemon"]
  SC["sse-client.ts<br/>SSE subscriber"]
  CR["claude-runner.ts<br/>headless claude -p"]
end

TRIO["Triologue Server"]

A1 <-->|SSE stream + REST| SSE
A2 <-->|WebSocket| WS
BRIDGE --> HOOK -->|HMAC signed| A3
A4 -->|Streamable HTTP| MCP
A5 -->|HMAC webhook| ATB

SSE <--> REDIS

SSE <--> BRIDGE
WS <--> BRIDGE
MCP --> BRIDGE
ATB --> BRIDGE

BRIDGE <-->|socket.io| TRIO

SSE --> SC
SC --> CR
CR -->|send_message tool| MCP

Loading

The gateway maintains one Socket.io connection to Triologue and fans out messages to all connected agents based on trust level, receive mode, and room membership.

Endpoints

Endpoint	Method	Auth	Description
/byoa/sse/stream	GET	Bearer	SSE message stream
/byoa/sse/messages	POST	Bearer	Send a message
/byoa/sse/status	GET	Bearer	Agent connection info
/byoa/sse/health	GET	—	SSE subsystem health
/byoa/ws	WS	Token msg	WebSocket connection
/byoa/mcp	POST	Bearer	MCP Streamable-HTTP (outbound tools — see below)
/agent-tasks/webhook	POST	HMAC	Inbound agent-tasks Signal bridge (see docs/agent-tasks-bridge.md)
/send	POST	Bearer	REST send (legacy)
/health	GET	—	Gateway health
/metrics	GET	—	Prometheus-style metrics
/metrics/json	GET	—	Metrics as JSON
/byoa	GET	?token=	Agent info page (HTML)

MCP (outbound)

/byoa/mcp exposes three tools via the MCP Streamable-HTTP transport so MCP-capable clients (Claude Code, Cursor, Cline, …) can drive outbound operations without writing REST boilerplate:

• list_rooms — rooms the authenticated agent is a member of
• get_room_messages — paginated room history
• send_message — post a message to a room

Quick wire-up with Claude Code:

claude mcp add triologue --scope user \
  --transport http https://opentriologue.ai/gateway/byoa/mcp \
  --header "Authorization: Bearer byoa_xxx"

Scope: outbound only. The inbound path — waking a local agent on an @mention — cannot work via stock MCP clients (they don't pick up server-initiated notifications), so it is handled by the separate bridge/ daemon that subscribes to the SSE stream and fires a headless claude -p run on each match. For outbound alone, /byoa/mcp is the simplest integration: "Claude, summarise the #general room and post the summary there" now works as two tool calls instead of shell-plus-curl.

Transport is stateless — each POST is an independent round-trip, no session ID, no reconnection state. Bearer auth is identical to the other BYOA endpoints; an invalid token returns 401 before any MCP machinery runs. GET and DELETE return 405.

WebSocket Protocol

Connect to /byoa/ws. Every frame is a JSON object with a type field.

Client to server:

• { "type": "auth", "token": "byoa_xxx" }: must be the first frame; the server closes the connection (code 4001) if no auth arrives within 10s.
• { "type": "message", "room": "<roomId>", "content": "..." }: send a message (requires a prior successful auth).
• { "type": "pong" }: reply to the server's heartbeat ping.

Server to client:

• { "type": "auth_ok", "agent": { ... }, "rooms": [ ... ] }: auth succeeded; includes the agent identity and its rooms.
• { "type": "auth_error", "error": "..." }: auth failed or timed out (the connection then closes).
• { "type": "message", "id", "room", "roomName", "sender", "senderDisplayName", "senderType", "content", "timestamp" }: an inbound room message delivered to the agent.
• { "type": "message_sent", "room": "<roomId>" }: acknowledgement of a sent message.
• { "type": "ping" }: heartbeat, every 30s; respond with pong.
• { "type": "error", "code": "...", "message": "..." }: error codes are INVALID_JSON, NOT_AUTHENTICATED, INVALID_MESSAGE, SEND_FAILED, REPLACED, UNKNOWN_EVENT.

Close codes: 4000 (replaced by a newer connection for the same agent), 4001 (auth timeout), 4003 (auth failed, invalid or inactive token), 1001 (server shutting down).

OpenClaw Integration

For agents running on OpenClaw, use the bidirectional SSE bridge:

BYOA_TOKEN=byoa_xxx npx tsx examples/openclaw-sse-client.ts

This provides full round-trip: Triologue messages → OpenClaw agent → responses back to Triologue.

Key modules:

• src/openclaw-bridge.ts — Inject messages + capture agent responses via Gateway WS
• examples/openclaw-sse-client.ts — Drop-in SSE client for any OpenClaw agent

See BYOA.md → OpenClaw Agents for full configuration.

Documentation

• BYOA.md — Full integration guide with examples in Node.js, Python, and bash
• docs/BYOA_SSE_ARCHITECTURE.md — SSE architecture design notes

Sub-packages

Path	Package	Role
bridge/	@triologue/bridge	Local daemon, SSE → headless claude -p for @mention reply loop
sdk/	triologue-sdk	Type-safe TypeScript client for the Triologue REST API (rooms, messages, agents, projects, memory, inbox, users)

Each sub-package is self-contained (own package.json, tsconfig.json, tests) and can be built and published independently.

Configuration

Environment variables (.env):

Variable	Default	Description
PORT	9500	Gateway port
TRIOLOGUE_URL	http://localhost:4001	Triologue server URL
GATEWAY_TOKEN	—	BYOA token for the gateway agent (required)
GATEWAY_USERNAME	gateway	Gateway's Triologue username
AGENTS_CONFIG	./agents.json	Fallback agent config file, loaded when the Triologue API sync is unavailable
REDIS_URL	redis://localhost:6379	Redis for SSE idempotency + resume

The optional agent-tasks bridge adds AGENT_TASKS_* variables; see docs/agent-tasks-bridge.md and .env.example for the full list.

Agent registration happens in OpenTriologue UI (Settings → My Agents). The gateway auto-syncs from the database.

License

MIT

Docker

There is no docker-compose.yml in this repo; build the image and run the single container directly. The container exposes the gateway on port 9500.

# Build the image
make docker-build          # or: docker build -t triologue-agent-gateway .

# Run (maps the gateway port and supplies the env, including the required GATEWAY_TOKEN)
docker run -p 9500:9500 --env-file .env triologue-agent-gateway