Decision gates

When an agent reaches something only a person should decide, it opens a gate and stops. You answer on the phone, in the desktop app, in the web terminal or with st gate answer, and the answer comes back to the agent as its next message.

When an agent reaches something you should decide (a design direction, something risky), it opens a gate and stops its turn. You answer wherever you are, and st types the answer into the agent so it carries on. Coordinators and workers can both open gates. st 0.3.83 or later.

st gate ask "How should images be handled?" --title "Images" \
  --option "A: keep them as attachments" --option "B: OCR to text" --text
st gate list                     # the open gates
st gate answer <id> 2            # answer here (options count from 1)

Asking

st gate ask "<question>" asks from the pane it runs in.

  • --option "<text>" once for each option.
  • --title "<few words>" a few words that name the question.
  • --text lets the answer be words instead of, or besides, an option.

The agent then stops its turn; the answer arrives as its next message.

Answering

  • On the phone. A push comes with the options as buttons.
  • In the desktop app and the web terminal. The question shows, with a ? on that agent's window.
  • In a terminal. st gate answer <id> <n> picks option n (counting from 1); st gate answer <id> "<text>" answers in words, and a number followed by words does both.

Answer anywhere. st then types "Decision gate … answered: B — …" into the agent as its next message, and it carries on.

Seeing and taking back

st gate list            # the open gates
st gate list --all      # answered and cancelled ones too
st gate show <id>       # one gate, its options and its answer
st gate cancel <id>     # take it back

With workers

  • A worker on a gate makes st worker wait and st task wait return "a worker is asking" (exit 3), so the coordinator knows it is waiting on you, not on the worker.
  • Open gates survive a restart of st.
  • Every gate command takes --json.

To answer an agent's question from the phone step by step, see the recipe Answer an agent's question from the phone.