SignalR

SignalR is Sophon's real-time transport. The Dashboard, Mobile, Desktop, and Sophon Node all connect to SignalR hubs for streaming, live status, and bidirectional commands. This page is the protocol reference.

Hubs

Sophon exposes six hubs, mounted under /hubs/*:

A single client can connect to multiple hubs over one WebSocket (SignalR multiplexes).

Authentication

Same JWT bearer as REST. Pass via query string (SignalR's WebSocket limitation):

import { HubConnectionBuilder } from "@microsoft/signalr";

const connection = new HubConnectionBuilder()
  .withUrl("https://gw.example.com/hubs/chat", { accessTokenFactory: () => jwt })
  .withAutomaticReconnect()
  .build();

Chat hub

await connection.invoke("SendMessage", {
  sessionId: "sess_abc",
  agentId: "sophon",
  content: "What's on my calendar today?",
  channelId: "webchat",      // or null for default
  attachments: [],
  isStreaming: true
});

Server → client events:

Client → server methods:

Tasks hub

Subscribes to the task ledger (all tasks, not just one session).

Server → client:

• TaskQueued, TaskStarted, TaskCompleted, TaskFailed — same shapes as chat hub
• TaskCancelled — {taskId, cancelledBy}

Client → server:

• Watch — start receiving events (no args; server pushes all tasks for the user)
• Unwatch — stop receiving events

Approvals hub

Drives the pending-approval queue.

Server → client:

Client → server:

Node hub (/hubs/node)

Bidirectional command channel between the Gateway and Sophon Nodes. Nodes connect as clients.

Gateway → Node (methods Nodes implement):

Node → Gateway:

See Sophon Node for command semantics and Node Protocol for field schemas.

Discussion hub

Server → client:

Client → server:

• Subscribe / Unsubscribe — by runId
• CancelRun — {runId}

Notifications hub

Generic pub/sub for user-scoped events. Used by the Home feed, insight cards, and any event clients want to watch live.

Events:

• InsightCardAdded / InsightCardDismissed
• WorkflowRunStarted / WorkflowRunCompleted / WorkflowRunFailed
• CronFired / CronFailed
• DocumentUploaded / DocumentIndexed
• NodeOnline / NodeOffline
• SystemAnnouncement — {title, body, severity} for admin-broadcast messages
• LicenseWarning — license expiring / expired (admin only)

Groups

SignalR groups are the mechanism for user / tenant / session scoping:

• user:{userId} — every event for this user
• tenant:{tenantId}:{userId} — every event for this user in this tenant (when multi-tenant)
• session:{sessionId} — every event in a specific chat session
• task:{taskId} — events for one specific task
• workflow:{workflowId} — workflow run events
• node:{nodeId} — command / heartbeat events for one node

Clients are auto-joined to user:{userId} on connect. Other groups are joined on Subscribe-style methods.

Reconnection

SignalR's withAutomaticReconnect() handles network blips. Reconnection retries with exponential backoff (0 ms, 2 s, 10 s, 30 s, then every 30 s).

On reconnect:

• Subscriptions are re-established (groups rejoined)
• Missed events are not replayed — use REST to catch up (e.g., GET /tasks/{id} for task state)
• Streaming tasks that were in flight continue; the client sees a possibly-incomplete stream followed by TaskCompleted once the task finishes

Backpressure

Server buffers outgoing events per-connection (default: 100 events). Beyond that, the slowest consumer is dropped. This prevents a slow client from OOMing the Gateway.

The mobile app and Dashboard rarely hit this. Custom SignalR clients that can't keep up should either fan out to a queue or switch to polling REST.

Transport selection

Preference order:

1. WebSockets — default; lowest latency, bidirectional
2. Server-Sent Events — for browsers that block WebSockets
3. Long polling — fallback for restrictive proxies

Sophon Node additionally supports HTTP polling fallback (GET /api/nodes/me/commands) for environments where WebSockets are blocked outbound.

Client examples

TypeScript (browser)

import { HubConnectionBuilder } from "@microsoft/signalr";

const conn = new HubConnectionBuilder()
  .withUrl("https://gw.example.com/hubs/chat", { accessTokenFactory: () => jwt })
  .withAutomaticReconnect()
  .build();

conn.on("StreamChunk", (c) => process.stdout.write(c.delta));
conn.on("TaskCompleted", (c) => console.log("\nDone in", c.durationMs, "ms"));

await conn.start();
await conn.invoke("SendMessage", {
  sessionId, agentId: "sophon", content: "hi", isStreaming: true
});

.NET / C#

var conn = new HubConnectionBuilder()
  .WithUrl("https://gw.example.com/hubs/chat", o => o.AccessTokenProvider = () => Task.FromResult(jwt))
  .WithAutomaticReconnect()
  .Build();

conn.On<StreamChunkEvent>("StreamChunk", c => Console.Write(c.Delta));
await conn.StartAsync();
await conn.InvokeAsync("SendMessage", new { sessionId, agentId = "sophon", content = "hi", isStreaming = true });

Python (signalrcore)

from signalrcore.hub_connection_builder import HubConnectionBuilder

hub = (HubConnectionBuilder()
  .with_url(f"https://gw.example.com/hubs/chat?access_token={jwt}")
  .with_automatic_reconnect()
  .build())

hub.on("StreamChunk", lambda msg: print(msg[0]["delta"], end=""))
hub.start()
hub.send("SendMessage", [{"sessionId": sid, "agentId": "sophon", "content": "hi", "isStreaming": True}])

Where to go next

• REST API — everything SignalR doesn't stream
• Node Protocol — the Node-specific hub contract
• Webhooks — for consumers that prefer push over WebSockets