Agents

Runs, approvals and signals

Every time a workflow runs, that's a run. SpudSuite queues it, a runner with room and the right labels takes it, and the runner reports each step back as it goes. Runs can wait for days, for a person or a signal, without holding the runner.

#Run states

queued → running → (waiting ↔ running)* → succeeded | failed | cancelled | lost

A run is waiting when it's parked on an approval or a signal. It's lost when its runner stops reporting and the run's lease runs out, for example because the machine was switched off.

#The run page

Open a run from Runs, a workflow, or the overview. It shows the run's status, who started it, its inputs and outputs, each step with its output and errors, and the full list of events in order. It updates while you watch.

#Approvals

An approval step pauses the run until a person decides:

- id: review
  type: approval
  message: "Ship the fix for {{ inputs.issue }}?"
  approvers: [dana@acme.com]

While it waits, the run page and the overview show Approve and Reject, with an optional comment. When the step lists approvers, only they can decide. A rejection stops the run. The same decision can come from the API:

curl -X POST "https://spudsuite.com/api/agents/runs/$RUN_ID/approve" \
  -H "Authorization: Bearer $SPUDSUITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step": "review", "approved": true, "comment": "Looks good"}'

#Signals

A wait step with a signal pauses until something sends data into the run:

- id: deployed
  type: wait
  signal: {name: deployed}

Send one from the run page, or from another system:

curl -X POST "https://spudsuite.com/api/agents/runs/$RUN_ID/signals/deployed" \
  -H "Authorization: Bearer $SPUDSUITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"env": "prod"}}'

#Cancelling

Cancel on the run page stops a run. The runner stops its steps at their next checkpoint.