session-control: add SessionControlCapable interface

[abhichothani42]

Summary

Adds a push-based contract for hardware that drives SessionManager state transitions (start, stop-early, re-record, stop-session). The VR session-control component (later in the stack) and the keyboard source implement it.

Changes

• SessionControlEvent enum: semantic intents, not raw inputs. kStart means "advance" — its effect (begin / stop-and-advance / skip-reset) is resolved by the host's event handler based on the current session phase.
• SessionControlCapable mixin: set_callbacks(on_event, on_disconnect), start(), stop(). The source owns its own threading and keeps callbacks cheap; disconnect is a one-shot end-of-session signal.
• Header-only interface, no dependencies.

Test Plan

• Builds cleanly (make build)
• Tests pass (make test)
• Lint passes (pre-commit run --all-files)
• Tested on hardware

Breaking Changes

None.

Related Issues

N/A — part of the VR teleoperation feature stack.

[abhichothani42]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• scripts: add Foxglove user scripts for robot and EEF visualization #277
• scripts: add URDF extraction tool for TrossenMCAP recordings #276
• examples: enable robot description recording in solo demo #275
• backend: write robot description to TrossenMCAP files #274
• config: add robot description options to TrossenMCAP backend #273
• utils: add RobotDescriptionCache for URDF download and mesh embedding #272
• examples: update sanity check for end-effector pose #270
• arm: emit end-effector pose from TrossenArmProducer #269
• backend: add end-effector pose write support to TrossenMCAP #268
• arm: add EndEffectorPoseRecord and proto schema #267
• examples: add trossen_vr_mobile demo #266
• examples: add trossen_vr_stationary demo #265
• examples: add trossen_vr_solo demo #264
• vr: add VrSessionControlComponent button-to-session bridge #263
• vr: add VrBaseComponent base-velocity teleop leader #262
• vr: add VrArmComponent cartesian teleop leader #261
• vr: add shared VrSession connection owner #260
• feat: post_event/attach_control queue for thread-safe session control #271
• session-control: add SessionControlCapable interface #259 👈 (View in Graphite)
• hw: make SlateBaseComponent a base-velocity teleop follower #258
• teleop: add base-velocity (Base) space to teleop interface #257
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Pull request overview

Adds a new public session-control interface in the hardware layer to allow a push-based source (e.g., keyboard/VR input) to emit high-level session intents to the runtime session orchestration.

Changes:

• Introduces SessionControlEvent to represent session-level control intents (start, stop-early, re-record, stop session).
• Adds SessionControlCapable interface with callback registration plus start()/stop() lifecycle for event production.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shantanuparab-tr]

The interface is header-only with nothing compiling it yet, so the "tested on hardware" box doesn't hold. Uncheck it.

[shantanuparab-tr]

• The disconnect signal is supposed to fire only once. Right now each component has to get that right on its own. Can the base class guarantee it instead?
• Please note which thread the callbacks run on, and that stop() finishes the worker before the callbacks go away. Also, kStart means different things at different points, so it is worth explaining at the definition. The design itself is good, keep it small.
• This is just an interface with nothing using it yet, so "tested on hardware" cannot be true here. Worth unchecking.

[shantanuparab-tr]

These functions are only safe to call from the main loop. This new design calls in from a separate thread, so the header should say clearly what a callback is allowed to call. Otherwise someone will call stop_episode() from the wrong place and cause a clash.

[abhichothani42]

Added, the header now spells out that callbacks run on the source's thread and must not call the SessionManager episode methods directly

[shantanuparab-tr]

changes requested

[shantanuparab-tr]

https://chat.google.com/room/AAQA0xpz-dM/TWmxsM3rgN0/TWmxsM3rgN0?cls=10

Check this for a suggestion of the session control rework

[abhichothani42]

"The disconnect signal is supposed to fire only once. Right now each component has to get that right on its own. Can the base class guarantee it instead?"
-> Moved it into the base now signal_disconnect() fires at most once per drop and arm_disconnect() re-arms on reconnect, so no component re-implements it.

Please note which thread the callbacks run on, and that stop() finishes the worker before the callbacks go away. Also, kStart means different things at different points, so it is worth explaining at the definition.
-> Documented at the enum definition.

-> Unchecked Tested on hardware

About session control rework
https://chat.google.com/room/AAQA0xpz-dM/TWmxsM3rgN0/TWmxsM3rgN0?cls=10
-> Done, added post_event/attach_control/drain to SessionManager in pr #271, and all three demos now go through it instead of touching the session from the callback thread. Details in that PR.