SignalRNEW

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. As of 1.11.0, task stream, status, lifecycle, and approval events are delivered to the session group rather than the whole user — see Session scoping.

Client → server methods:

Session scoping

As of 1.11.0, JoinSession(sessionId) is the primary subscription mechanism, and per-task events target the session group instead of broadcasting user-wide:

• Clients are auto-joined to sessions they create — sending the first message on a new session subscribes you implicitly.
• Ownership is validated on every join — a client can only join sessions owned by its user (and tenant). The Canvas (whiteboard) hub validates session ownership on join the same way.
• Legacy clients that never call JoinSession fall back to user-wide events, so older integrations keep working unchanged.

This is what keeps multiple devices from interfering: a Dashboard tab watching one session never receives another session's stream chunks, and approvals shown in the CLI aren't disturbed by activity on other devices. Devices not joined to a session still learn about its activity via SessionNotification.

SessionNotification

SessionNotification is a lightweight, user-wide activity event — every connected device receives it, whether or not it has joined the session:

The excerpt gives clients a short preview to render; full message content and detail still require JoinSession or REST. Clients use the event to update unread badges and pending-approval counters. The Desktop app's native notifications are driven by this event.

Voice streaming

StreamAudio(sessionId, audioChunks, mode?) is a client-to-server streaming method for realtime speech-to-text:

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

const audioChunks = new Subject<string>();
await connection.send("StreamAudio", sessionId, audioChunks, "Auto");

// feed base64-encoded PCM chunks as the mic produces them
audioChunks.next(base64Chunk);
// Manual mode only: end the utterance explicitly
audioChunks.complete();

• Audio format — 16 kHz mono linear16 PCM, base64-encoded per chunk. This works over the standard SignalR JSON protocol; no binary transport is required.
• mode: "Auto" (default) — hands-free; the STT provider's pause detection ends the utterance.
• mode: "Manual" — push-to-talk; the client ends the stream by completing it.

Transcripts are delivered only to the connection streaming the audio — not to the session group, so other devices joined to the session don't see them: VoiceInterimTranscript fires while the user speaks (each interim replaces the previous one), and VoiceFinalTranscript carries the committed utterance, which enters the agent pipeline like a typed message. See Voice for provider setup and per-user listening preferences.

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. As of 1.11.0, all group names are tenant-qualified — session groups are scoped to the tenant that owns the session, and user groups are prefixed with the tenant ID. A shared Gateway hosting multiple tenants can never deliver one tenant's events to another tenant's connections. See Tenants & Multi-Tenancy.

Clients are auto-joined to their user group on connect and to session groups for sessions they create. Group names are server-internal — clients only ever pass IDs (sessionId, taskId, runId) to subscribe 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

Rejoining mid-task: after JoinSession, fetch the persisted message (GET /sessions/{id}/messages) and replace any partial stream buffer with it — appending renders duplicated text. Guard for staleness: the probe may discover the task already finished while you were reconnecting; in that case render the final message and don't re-arm any waiting or streaming state. The Dashboard and Mobile apps do this automatically.

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
• Voice — STT/TTS provider configuration behind StreamAudio