ServicesBuilt-in Services
shell Built-in Service
Explain the built-in shell service as the owner of shell session state, execution lifecycle, and stateful command interaction
shell Built-in Service
shell is the built-in service for short and long-running shell execution.
It is responsible for:
- one-shot command execution
- stateful shell sessions
- incremental reads and writes
- waiting on session state changes
- closing and cleaning up sessions
What it owns
From the current implementation, shell owns:
- the shell service state object
- the in-memory shell session map
- runtime binding to the current agent context
- lifecycle cleanup for all active sessions
Why this is a service instead of a tool
Shell execution is not only “run a command”.
The real problem is ownership of:
- session identity
- buffered output
- long-running process state
- lifecycle cleanup
That is why shell belongs in a service.
Why SDK users should care
shell is one of the clearest built-in examples for stateful execution.
If you are designing a service that must manage:
- resource pools
- active sessions
- waiters
- cleanup
the shell model is a strong reference.
Best mental model
Think of shell as the execution runtime, not just a command wrapper.
The agent reasons about work.
The shell service owns the process-level state that lets that work stay queryable over time.