Sessions

┌─────────────────────────────────────────────────────────────┐
│                        Session Object                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  id: UUID                    # Globally unique identifier    │
│  status: SessionStatus       # Lifecycle state               │
│  workspace: Workspace        # Tenant isolation              │
│  machine: Machine            # Associated agent              │
│  created_at: datetime                                        │
│  connected_at: datetime                                      │
│  last_heartbeat_at: datetime                                 │
│  grace_period_started_at: datetime                           │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Execution Context                       │    │
│  │  • Running processes                                 │    │
│  │  • Environment variables                             │    │
│  │  • Working directory                                 │    │
│  │  • Command history                                   │    │
│  │  • Output buffer                                     │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

# SSH ties session lifetime to a single connection; CMDOP decouples them
Traditional SSH:
  Connection ═══════ Session
  └─ Connection closes → Session dies

CMDOP:
  Connection ────┐
  Connection ────┼───▶ Session (persistent object)
  Connection ────┘
  └─ Connections come and go, session persists

# Demonstrates session persistence across client disconnects
# Client 1: Start long-running process
await client.terminal.execute("./train_model.py")
 
# Client 1 disconnects (laptop closes)
# Session enters GRACE_PERIOD, but:
# - Process keeps running
# - Output is buffered
# - Session is not terminated
 
# Client 2 (or same client): Reconnect and reattach
await client.terminal.attach(session_id)
# See live output, process still running

# Each session belongs to exactly one workspace and one machine
Workspace: "acme-corp"
├── Machine: "prod-server-1"
│   └── Session: abc-123
├── Machine: "prod-server-2"
│   └── Session: def-456
└── Machine: "staging-1"
    └── Session: ghi-789

# Scenario: Network hiccup during critical operation
 
# Without grace period (traditional SSH):
# Command may be half-executed if connection drops — disaster!
await client.terminal.execute("rm -rf /old/data && mv /new/data /current")
# Network drops for 5 seconds
# SSH session dies
# Command may be half-executed — disaster!
 
# With CMDOP grace period:
# Session persists through brief network interruptions
await client.terminal.execute("rm -rf /old/data && mv /new/data /current")
# Network drops for 5 seconds
# Session enters GRACE_PERIOD
# Command continues executing
# Network recovers, client reconnects
# Session continues normally

# Sessions are created server-side when the agent connects
# On the agent (Go)
agent.connect()  # Creates session on Control Plane

# Retrieve all sessions in the current workspace
response = await client.terminal.list_sessions()
for session in response.sessions:
    print(f"{session.machine_hostname}: {session.status}")

# Look up the active session for a specific machine by hostname
session = await client.terminal.get_active_session("my-server")
 
# Open a bidirectional stream and attach to the session
stream = client.terminal.stream()
await stream.attach(session.session_id)

# Close the stream without terminating the session
await stream.close()
# Session continues, can be reattached

# AI attaches in read-only mode to analyze terminal output in real-time
session = await client.terminal.get_active_session("prod-server")
 
# Attach AI as observer — can read output but cannot send input
ai_stream = client.terminal.stream(mode="observer")
await ai_stream.attach(session.session_id)
 
# Register callback to analyze each output chunk
ai_stream.on_output(analyze_and_suggest)

# Dev starts session at office
await stream.attach(session_id)
await stream.send_input("./deploy.sh")
 
# Dev leaves office (detaches, but session continues on the agent)
await stream.close()
 
# Ops takes over from phone — same session, different device
mobile_stream = client.terminal.stream()
await mobile_stream.attach(session_id)  # Same session!
# Sees deploy progress, can intervene

# Good: Reuse an existing active session instead of creating a new one
session = await client.terminal.get_active_session("my-server")
await stream.attach(session.session_id)
 
# Avoid: Creating new sessions frequently
# (Only agents should create sessions)

# Good: Atomic operation that completes fully or not at all
await client.terminal.execute("mv /tmp/new /app/current")
 
# Better: Resumable operation that can recover from interruption
await client.terminal.execute("rsync -avz --partial /src /dst")

# Always verify session state before running commands
session = await client.terminal.get_active_session("server")
if session.status != "CONNECTED":
    print(f"Warning: Session is {session.status}")