Sessions & modes

Console sessions are agent-runtime state. They are not persisted across agent restart. There is no silent reconnect after underlying Telnet loss.

Session model

  • Every Hub-backed consumer needs an explicit session_id (opaque string issued by the agent).
  • Sessions belong to a (lab, node) pair and a write mode.
  • Closed sessions are terminal — create a new session to continue.
  • Do not assume durable session or history state in automation scripts.

Hub lifecycle

  1. First lease on a node opens (or reuses) a Hub and dials one EVE Telnet TCP connection.
  2. Console bytes (after Telnet IAC filtering) append to a 64 KiB ring buffer.
  3. When the last client disconnects or closes its session, the Hub enters idle retention for 60 seconds.
  4. After idle expiry, the Hub and its history are removed.
  5. The agent supports at most 64 concurrent Hubs.

History exists only while the Hub exists. There is no background log collector and no persistent transcript in V1.

Write modes

Security is agent-enforced, not client-side honor system.

Mode Writes Typical use
observe Rejected by the agent Read-only watch, CI checks
interact Multiple writers allowed Human + AI collaboration
exclusive One writer owner; observers may remain Single automation owner

Omitted mode on attach or create = interact.

In exclusive mode, V1 does not support stealing an existing writer. Observers with observe may still attach.

Explicit session sharing

VSIX Open Console, CLI attach, SDK attach, and MCP/SDK automation can share one Hub and one EVE Telnet TCP only when they use the same explicit session_id.

Engineer opens R1 in VSIX  →  session_id = abc123
AI/MCP uses session_id=abc123  →  same Hub  →  same EVE console TCP

An explicit session_id still names one Hub lease, so a human terminal and an automation call can share one EVE Telnet TCP.

execConsole and runConsole join or open the Hub for the node when session_id is omitted. A session_id that is no longer present is reopened once. console_busy (an exclusive writer) is not treated as expiry. Listing sessions is optional. See Exec, wait, run.

VSIX Open Console

Interactive consoles in VS Code / Cursor use the generated SDK against the agent — never raw EVE Telnet from the workstation.

createConsoleSession  (default mode interact)
        ↓
attachConsole(session_id)
        ↓
streamConsole  →  HTTP 101 Upgrade: eve-telnet
  • Omitted mode = interact.
  • The VSIX retains session_id on the terminal for shared use.
  • Closing the terminal calls closeConsoleSession and releases that lease.
  • Ctrl+C (0x03) is forwarded to the node; it is not used to detach.
  • HTML5 VNC/RDP for graphical nodes is a separate flow and is unchanged.

Do not open telnet:// URLs or EVE console ports from the operator workstation.

CLI session helpers

Command Purpose
eve-iac console sessions PROJECT List active sessions
eve-iac console close PROJECT --session ID Close a session

Attach escape sequences (~., ~d, …) are documented on Console CLI. They are local to the CLI attach client, not part of the wire protocol.