Session Lifecycle & Method Namespace

9. Session lifecycle

TCP connect
  │
  ▼
Handshake (pair or auth) → EncryptedConnection
  │
  ▼
HELLO exchange (one frame each direction, simultaneous)
  │  client.hello(my_manifest) ──► server.hello(my_manifest)
  │  client ◄── server HELLO (capabilities + optional error)
  │
  ▼  [server HELLO error → ProtocolError, connection closes]
  │
  ▼
peer.start()  ← spawns background recv loop
  │
  ├── outbound: peer.call(method, params) → result dict
  │                or peer.stream(method, params) → AsyncIterator
  │
  ├── inbound:  Dispatcher.call / Dispatcher.stream (server side)
  │
  ├── push:     peer.push(topic, payload)  /  peer.on_push(handler)
  │
  ▼
peer.aclose() or connection drop
  └── all in-flight calls fail with ConnectionClosed

Single-controller invariant (server side): at most one session exists at a time. The accept_lock in OpendeskServer._handle_connection serialises the “check-existing + register-new” step:

• Same peer reconnecting → old session evicted (session.evicted PUSH sent), new session registered.

• Different peer while one is active → HELLO sent with error.code = "busy", connection closed.

---

10. Method namespace

Method names are <namespace>.<verb> strings. The full set dispatched by ComputerDispatcher:

Observation methods (auto-approved by ConsolePolicy)

Method	Description
display.capture	Screenshot → Pixmap
display.displays	List monitors
display.cursor_position	Current pointer position
display.subscribe	Streaming display frames
windows.list	All windows
windows.focused	Focused window
ui.tree	Accessibility element tree
clipboard.read	Read clipboard contents
fs.read	Read file bytes
fs.list	List directory
fs.stat	File metadata
process.list	Running processes
apps.list	Installed / running applications
notifications.list	Recent notifications
input.subscribe	Streaming input events
system.capabilities	Capability manifest
system.environment	Environment variables + platform info

Action methods (require policy approval)

Method	Description
input.pointer	Mouse move / click / drag / scroll
input.key	Key press / release / chord
input.text	Type a string
apps.open	Launch application
apps.close	Quit application
apps.focus	Bring application to front
windows.focus	Focus a specific window
windows.move	Reposition / resize a window
windows.close	Close a window
ui.perform	Perform accessibility action on element
clipboard.write	Write clipboard contents
fs.write	Write file bytes
fs.delete	Delete file or directory
fs.move	Move / rename file
fs.mkdir	Create directory
process.shell	Run shell command
process.exec	Run process directly (no shell)
system.lock	Lock the screen

---

Last section: Discovery, Admin IPC & Cryptographic Summary →