Skip to content

Runs

A run is one work item of the gateway: one task for a team's lead, from the moment it arrives until the lead declares it done, failed or cancelled. Its conversation is the list of posts the team made in it.

States

State Meaning
running Some role is working.
waiting A role needs a person: a question or a confirmation. GET /runs/{id} names who and since when (waiting_for), and open_question holds the question.
succeeded The lead said it is done; delivery names the branch and pull request.
failed failure_reason says why.
cancelled Stopped by a person.

Giving a team a task

From a chat room or an issue tracker, work arrives as it does today. From the Console, a team has a task box (POST /teams/{name}/tasks); the team answers in the run's conversation without any chat surface. A team that lives on Mattermost or Slack takes its tasks there, and the route answers 409 for it.

Following a run

  • GET /runs and GET /teams/{name}/runs list runs, newest first.
  • GET /runs/{id} has the state, the tasks of every role, the cost, a link to the chat thread and a link to the trace.
  • GET /runs/{id}/posts is the conversation in order; pass the last seq seen as cursor to read only what is new. Kinds: notice, working, question, answer, completed, failed, canceled, task, reply, artifact and command_result.
  • GET /runs/{id}/trace shows which role did what and what each step cost.

Answering, following up, cancelling

  • A waiting run is answered with POST /runs/{id}/replies and {text, in_reply_to: <open_question.seq>}. Without in_reply_to the text is a follow-up task in the same run.
  • POST /runs/{id}/cancel stops a run.
  • A run that lives on a chat surface is answered and cancelled there (409 from the routes).

All three need the operator role. The Console's run page has the same controls. The playbooks show the calls in order, and limits has the size of a task and a reply.

Cost

Spend is attributed per team, role and agent key by LiteLLM, so a run shows what it cost and the Spend page shows teams per day. A team whose budget is spent answers new tasks with 429.

Depth: architecture, Team flow and Cost and attribution.