Skip to content

feat: stop idle agent sandboxes using OSC 7501 program status #5852

Open

Description

@mrunalp

User Story

I use OpenShell to run Claude Code and Codex and other coding CLIs in sandboxes. A lot of a sandbox's life is spent with the agent waiting on me after it finishes a turn while the sandbox keeps its compute. I need OpenShell to notice when the agent has been waiting longer than a timeout I choose and stop the sandbox, then start it again when I connect, so idle agents stop holding capacity.

Problem Statement

OpenShell cannot tell an agent that is waiting on the user from one that is busy. The only activity signal the supervisor collects is a network connection summary for telemetry. An agent at its prompt and a quiet long-running build look the same from outside. Nothing stops a sandbox on its own, so idle sandboxes run until someone stops or deletes them.

Coding agents now declare their state on their own terminal with OSC 7501, the Program Status Protocol. Claude Code and Codex report idle, working, done, and blocked (for example, waiting on a permission prompt) natively. The workload PTY already passes through the supervisor, but OpenShell ignores these reports.

Impact / Why This Matters

Today users or operators find idle sandboxes and stop them by hand, or leave them running. A stopped sandbox must be started explicitly before connect works. On shared clusters, idle agent sandboxes hold CPU and memory reservations, nodes, or VMs that other work could use. Heuristics such as screen or title scraping need a parser per agent and break when the agent's UI changes.

Proposed Design

  • The supervisor reads OSC 7501 reports from workload terminals: the main process and interactive SSH sessions. It answers the protocol's support query itself, so reporting does not depend on the user's local terminal.
  • openshell sandbox get shows the latest report as a ProgramStatus condition, for example Done: claude-code is done.
  • A new runtime setting, idle_stop_after_seconds, sets the idle timeout at sandbox or gateway scope. Unset or zero disables it, which is the default.
  • When the program has reported idle, done, blocked, or error and no one has typed into a workload terminal for the timeout, the gateway stops the sandbox. It settles as Stopped with the reason IdleStopped.
  • openshell sandbox connect starts an IdleStopped sandbox before connecting. Explicitly stopped sandboxes keep today's behavior.
  • A sandbox whose programs never report status, or that reports working, is never stopped.
  • Phase 1 keeps today's stop semantics: workspace files persist, and process memory does not. The agent resumes its conversation with its own option, such as claude --continue. A later phase can use the existing SuspendSandbox and ResumeSandbox APIs for memory checkpoints once a driver supports them.

The design needs cross-cutting review across the supervisor, gateway lifecycle, settings, and CLI, so I'd like an RFC number assigned. A draft RFC is ready.

Suggested UX (if applicable)

# Stop this sandbox after its agent has waited 30 minutes
openshell settings set my-sandbox --key idle_stop_after_seconds --value 1800

# Or set a fleet-wide value (gateway scope wins over sandbox scope)
openshell settings set --global --key idle_stop_after_seconds --value 3600

openshell sandbox get my-sandbox
#   Conditions:
#     - ProgramStatus: Done (claude-code is done)

# After the timeout
openshell sandbox get my-sandbox
#   Phase: Stopped
#     - Ready: False IdleStopped

openshell sandbox connect my-sandbox
# Sandbox my-sandbox was stopped while idle; starting it
# ✓ Started sandbox my-sandbox

Acceptance Criteria

  • openshell sandbox get shows a ProgramStatus condition for a sandbox whose terminal program reports OSC 7501, and none for one that does not.
  • With idle_stop_after_seconds set, a sandbox whose program reports done and receives no terminal input for that long reaches Stopped with reason IdleStopped.
  • A sandbox whose program reports working, or never reports, is not stopped.
  • Terminal input resets the idle wait.
  • openshell sandbox connect starts an IdleStopped sandbox and connects; an explicitly stopped sandbox still returns an error.
  • Idle stop is off unless the setting is set.
  • No fields are added to public Sandbox, SandboxSpec, or SandboxStatus messages.
  • Conformance coverage runs a scripted OSC 7501 program through idle stop and restart on each compute driver.

Alternatives Considered

  • Network or input inactivity alone. This needs no agent cooperation, but it cannot tell a quiet build from a waiting agent, so it would stop sandboxes mid-task.
  • Screen or window-title scraping. This needs a parser per agent and breaks when the agent's UI changes.
  • Agent hooks, such as Claude Code hooks. These need per-agent configuration in every sandbox image, and they run as workload code with network access.
  • Middleware or gateway interceptors. These see network or gRPC traffic, not the workload terminal, so they cannot observe the program's declared state.
  • Do nothing. Idle sandboxes keep their capacity until someone stops them by hand.

Agent Investigation

  • The prototype ran an OSC 7501 scanner in openshell-supervisor-process against Claude Code 2.1.327 and Codex 0.170.0 on a host PTY.
    • Claude Code queries for support at startup. It reports only if the reply arrives before the terminal answers its follow-up DA1 query, so the supervisor must answer.
    • Codex reports without querying.
    • Both report working then done per turn, and blocked:kind=permission at approval prompts.
  • A reply identical to the query loops forever when a program probes with echo on. The reply must use the spec's full form, OSC 7501 ; ? : states=... : kinds=... ST.
  • StopSandbox, StartSandbox, SuspendSandbox, and ResumeSandbox exist, but every driver returns UNIMPLEMENTED for suspend. Phase 1 therefore uses stop and start.
  • A working implementation passes unit tests, the existing attach, cli, ssh, exec, and lifecycle conformance suites, and a new idle-stop conformance test against a Docker gateway. It is not pushed yet.
  • Docker driver snapshots rewrite a stopped sandbox's Ready reason. The gateway keeps the idle reason with an internal.openshell.ai/ annotation and reapplies it.
  • Agents run inside tmux in the sandbox are not detected, because tmux does not forward the reports. Those sandboxes stay running.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions