Run Controls

Install

npx ax-depute@latest add run-controls

pnpm dlx ax-depute@latest add run-controls

yarn dlx ax-depute@latest add run-controls

bunx ax-depute@latest add run-controls

Overview

Minimal execution steering — pause, resume, stop, retry. Intentionally kept simple. Extend via the actions slot for additional controls.

Interactive StorybookView all states, toggle props, and test edge cases.

Basic usage

<Run Controls
  state="running"
  onPause={() => agent.pause()}
  onStop={() => agent.kill()}
/>

With local state

import { useState } from 'react';
import type { RunState } from '@/types/ax-common';

export function ExecutionWrapper() {
  const [state, setState] = useState<RunState>('running');

  return (
    <Run Controls 
      state={state} 
      showLabel={true}
      onStart={() => setState('running')}
      onPause={() => setState('paused')}
      onStop={() => setState('stopped')}
      onRetry={() => setState('running')}
    />
  );
}

Props

Prop	Type	Default	Description
`state`	`RunState`	Required	Current execution state (`'idle' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'stopped'`).
`onStart`	`() => void`	`undefined`	Callback fired when user clicks start or resume.
`onPause`	`() => void`	`undefined`	Callback fired when user clicks pause.
`onStop`	`() => void`	`undefined`	Callback fired when user clicks stop (cancel execution entirely).
`onRetry`	`() => void`	`undefined`	Callback fired when user clicks retry after a failure state.
`showLabel`	`boolean`	`false`	Whether to display a text label showing the current state next to the pulsing indicator.
`actions`	`ReactNode`	`undefined`	Slot for additional custom action buttons (e.g., an Undo button).

Composition flow

Run Controls is the central execution steering wheel, usually placed immmediately before or right next to an agent's Tool Trace:

Plan Card → Approval Gate → [Run Controls] → Tool Trace → Artifact Card

It controls whether the Tool Trace continues to append new events or pauses execution.

Why a "Big Red Button"? When an agent is operating autonomously, the human supervisor must always have an immediate, obvious way to halt it. Run Controls provides this physical-feeling override switch.

Why adapt to the state prop? The controls automatically adapt to the state prop. If the agent is already completed, the pause and stop buttons disappear. If it is failed, the retry button appears. This fundamentally prevents impossible state transitions without the developer writing extra UI conditional logic.