Gateway Session Sharing

Let multiple authorised clients observe or co-drive one live Gateway session

Session sharing lets more than one authorised client attach to the same live Gateway session — watching an agent work a task together, or opening the same conversation on desktop and mobile.

from praisonaiagents import Agent
from praisonai_bot.gateway import WebSocketGateway

agent = Agent(name="assistant", instructions="Be helpful.")
gateway = WebSocketGateway()
gateway.register_agent(agent, agent_id="assistant")

# Open the session as shared — a teammate can now attach and co-drive.
session = gateway.create_session("assistant", client_id="alice", visibility="shared")

# A second authorised client attaches as a member and co-drives through
# the normal message path (still gated by the ``write`` scope).
gateway.attach(session.session_id, "bob", role="member")

WebSocketGateway enforces the fan-out, and each observer’s OperatorScope decides which events it receives.

Quick Start

1. Default — private, 1:1 (nothing to configure)

   Today’s behaviour is unchanged. A session is private and stays bound to its single owner.

   from praisonai_bot.gateway import WebSocketGateway
   
   gateway = WebSocketGateway()
   session = gateway.create_session("assistant", client_id="alice")
   
   print(session.to_dict()["visibility"])  # "private"
   
   try:
       gateway.attach(session.session_id, "bob")
   except PermissionError as e:
       print(e)  # Session <id> is private

2. Share a session read-only

   Set read_only so an extra client may attach as a viewer to watch the stream, but not send.

   from praisonai_bot.gateway import WebSocketGateway
   
   gateway = WebSocketGateway()
   sid = gateway.create_session("assistant", client_id="alice", visibility="read_only").session_id
   
   gateway.attach(sid, "bob", role="viewer")
   
   try:
       gateway.attach(sid, "ann", role="member")
   except PermissionError as e:
       print(e)  # Session <id> is read-only; attach as viewer

3. Share a session for co-driving

   Set shared so an extra client may attach as a member and send turns alongside the owner.

   from praisonai_bot.gateway import WebSocketGateway
   
   gateway = WebSocketGateway()
   sid = gateway.create_session("assistant", client_id="alice", visibility="shared").session_id
   
   gateway.attach(sid, "ann", role="member")
   gateway.attach(sid, "bob", role="viewer")
   
   print(gateway.observers(sid))
   # [('alice', OWNER), ('ann', MEMBER), ('bob', VIEWER)]

How It Works

A member drives a turn, and the stream reaches the owner and every scoped observer — but only the owner’s copy is recorded for replay.

1. The owner creates the session — it is private unless visibility says otherwise.
2. Other clients attach as member or viewer, as the visibility allows.
3. A member is bound to the session, so its message frames co-drive it. A viewer is never bound, so it can never send.
4. Every stream event and the final response fan out to the owner plus each connected observer whose scope allows it.

Visibility

Visibility decides whether a second authorised client may attach on top of scope authorisation.

Roles

A role decides what an attached client may do inside a shared session.

Which visibility should I pick?

Visibility Enforcement (Dynamic Changes)

Call create_session again with the same session_id to change visibility on a live session — the gateway revokes any access the new setting no longer allows.

from praisonai_bot.gateway import WebSocketGateway

gateway = WebSocketGateway()

# Start shared with a member and a viewer
gateway.create_session("assistant", client_id="alice", session_id="s1", visibility="shared")
gateway.attach("s1", "ann", role="member")
gateway.attach("s1", "bob", role="viewer")

# Tighten to read-only — ann is demoted to viewer and can no longer send
gateway.create_session("assistant", client_id="alice", session_id="s1", visibility="read_only")
print(gateway.observers("s1"))
# [('alice', OWNER), ('ann', VIEWER), ('bob', VIEWER)]

# Tighten to private — every observer is dropped
gateway.create_session("assistant", client_id="alice", session_id="s1", visibility="private")
print(gateway.observers("s1"))
# [('alice', OWNER)]

Fan-out and Scopes

Visibility and role layer on top of OperatorScope — they are not authorisation.

• Streaming events (tokens, tool calls, tool results) and the final response frame fan out to the owner plus every attached observer whose OperatorScope allows that event.
• An observer without READ receives nothing, whatever its role.
• A member still needs WRITE to send a message frame — attaching alone does not grant it.
• The owner always receives its own session’s stream, even when a member drives the turn.
• Only the owner’s copy is written to the session’s replay buffer — observer copies are never recorded a second time.

Owner Leaving vs. Observer Leaving

An observer leaving only detaches it — the owner’s session stays open and the roster shrinks. This holds for every exit path: a leave frame, disconnect, the idle reaper, slow-consumer eviction, and credential rotation.

The owner leaving closes the session (persisted for resumption) and drops the whole observer roster. On a leave frame only the owner gets a {"type": "left", ...} reply; an observer’s leave just detaches it.

Observers Cannot Rebind as Owner

A client attached as an observer cannot take over the session by sending hello or join with that session’s id.

# bob is attached to "s1" as a viewer and sends:
{"type": "join", "agent_id": "assistant", "session_id": "s1"}

# The gateway replies:
{"type": "error", "code": "unauthorized", "message": "Attached observers cannot take over the session"}

On hello the gateway sends a HelloError with code=AUTH_UNAUTHORIZED, next_step=DO_NOT_RETRY and next_action="start_new_session".

Rules & Errors

Configuration

Every value maps to a wire string used on the protocol.

SessionVisibility

SessionSharingRole

Both accept the enum or its wire string. All imports use the friendly top-level path:

from praisonaiagents.gateway import (
    SessionVisibility,
    SessionSharingRole,
    SessionObserverProtocol,
)

Server API

WebSocketGateway implements SessionObserverProtocol.

visibility is saved with the session and round-trips through to_dict / from_dict; older snapshots without it load as private.

User Interaction Flow

Alice starts a research session on her laptop, watches it read-only from her phone, then opens it up so Bob can help steer the next turn.

from praisonaiagents import Agent
from praisonai_bot.gateway import WebSocketGateway

agent = Agent(name="researcher", instructions="Research topics thoroughly.")
gateway = WebSocketGateway()
gateway.register_agent(agent, agent_id="researcher")

# Alice owns the session on her laptop and opens it read-only
gateway.create_session("researcher", client_id="alice-laptop", session_id="research", visibility="read_only")

# Alice's phone watches the live token stream
gateway.attach("research", "alice-phone", role="viewer")

# Alice opens it up so Bob can co-drive
gateway.create_session("researcher", client_id="alice-laptop", session_id="research", visibility="shared")
gateway.attach("research", "bob", role="member")

print(gateway.observers("research"))
# [('alice-laptop', OWNER), ('alice-phone', VIEWER), ('bob', MEMBER)]

# Bob is done — the session keeps running for Alice
gateway.detach("research", "bob")

Best Practices

Related