Session Worker

The session worker provides process-level isolation for agent sessions. Instead of running all sessions in a single process, PRX can spawn dedicated worker processes that contain failures and enforce resource limits at the OS level.

Motivation

Process isolation provides several benefits:

• Fault containment -- a crash in one session does not affect others
• Resource limits -- enforce per-session memory and CPU limits via cgroups or OS mechanisms
• Security boundary -- sessions with different trust levels run in separate address spaces
• Graceful degradation -- the main process can restart failed workers

Architecture

┌──────────────┐
│  Main Process │
│  (Supervisor) │
│               │
│  ┌──────────┐ │    ┌─────────────┐
│  │ Session A ├─┼───►│ Worker Proc │
│  └──────────┘ │    └─────────────┘
│  ┌──────────┐ │    ┌─────────────┐
│  │ Session B ├─┼───►│ Worker Proc │
│  └──────────┘ │    └─────────────┘
└──────────────┘

The main process acts as a supervisor, communicating with workers via IPC (Unix domain sockets or pipes).

Communication Protocol

Workers communicate with the supervisor using a length-prefixed JSON protocol over the IPC channel:

1. Spawn -- supervisor sends session configuration to the worker
2. Messages -- bidirectional streaming of user/agent messages
3. Heartbeat -- periodic health checks
4. Shutdown -- graceful termination signal

Configuration

[agent.worker]
enabled = false
ipc_socket_dir = "/tmp/prx-workers"
heartbeat_interval_secs = 10
max_restart_attempts = 3

Resource Limits

When running on Linux, the session worker can apply cgroup-based resource limits:

[agent.worker.limits]
memory_limit_mb = 256
cpu_shares = 512

Related Pages

• Agent Runtime -- Architecture overview
• Agent Loop -- Core execution cycle
• Security Sandbox -- Sandbox backends