Run Controls
The transport bar for an agent run: start, pause, step, stop, replay. Which buttons exist is derived from status, so the invalid combinations — running and paused, replay while live — cannot be expressed.
src/components/ui/run-controls.tsxAbout
From the component's own source, where it was written.
The transport bar for an agent run: start, pause, step, stop, replay.
Stepping is what makes an agent debuggable. Watching one run at full speed tells you what it did; stepping tells you what it was about to do, which is the only moment you can still intervene.
**Stop is always available while anything is running, and never disabled by a pending state.** A run that has wedged is exactly when you most need to stop it, and that is exactly when a UI that disables the button during "stopping" leaves you with no way out.
Which buttons exist is derived from status, not from a pile of booleans at the call site — the invalid combinations (running *and* paused, replay while live) simply cannot be expressed.
Install
npx astralyx-ui add run-controls
Usage
import { RunControls } from '@/components/ui/run-controls'
<RunControls status={status} step={step} totalSteps={12} onPause={pause} onStep={stepOnce} onStop={stop} />Composer
Change the props and the source below follows.
No props to configure.
<RunControls
status={status}
step={step}
totalSteps={12}
onStart={start}
onPause={pause}
onStep={stepOnce}
onStop={stop}
onReplay={replay}
/>Examples
Driving a run
<RunControls status={status} onStart={start} onPause={pause} onStep={stepOnce} onStop={stop} />API
Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.
RunControls
The transport bar for an agent run: start, pause, step, stop, replay.
Extends Omit<ComponentProps<'div'>, 'onPause'>.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | — | Trailing slot — a model picker, a spend cap, a link to the trace. |
| status | RunStatus | required | The single source of truth. The button set is derived from it rather than from a pile of booleans at the call site. |
| onStart | () => void | — | — |
| onPause | () => void | — | — |
| onResume | () => void | — | — |
| onStep | () => void | — | Only offered while paused — stepping means nothing from a running clock. It is what makes an agent debuggable: you see what it was *about* to do. |
| onStop | () => void | — | Available whenever anything is live, including while stopping. A wedged run is exactly when you need it and exactly when a disabled button traps you. |
| onReplay | () => void | — | — |
| step | number | — | Progress readout. elapsed is pre-formatted — this component does not own your locale. |
| totalSteps | number | — | Progress readout. elapsed is pre-formatted — this component does not own your locale. |
| elapsed | ReactNode | — | Progress readout. elapsed is pre-formatted — this component does not own your locale. |
| startLabel | string | 'Run' | — |
| pauseLabel | string | 'Pause' | — |
| resumeLabel | string | 'Resume' | — |
| stepLabel | string | 'Step' | — |
| stopLabel | string | 'Stop' | — |
| replayLabel | string | 'Replay' | — |
| statusLabels | Partial<Record<RunStatus, string>> | — | — |
Types
| Type | Definition | Description |
|---|---|---|
RunStatus | 'idle' | 'running' | 'paused' | 'stopping' | 'done' | 'error' | — |