Sessions

A session is one run of work: a build, a migration, an agent’s task. It has a title, a headline of what it is doing now, its progress and the ask it is waiting on, if any, and the messages and asks sent in it belong to it.

Start, update, end

export KABU_SESSION=$(kabu session start --title "Migrate billing" --external-id run-77 | jq -r .id)
kabu session update --headline "Copying tables" --progress 2/5 --progress-label tables
kabu session end --outcome success --summary "All 5 tables copied"

Report progress only when it is measurable (items done of a known total) or for known steps; set --progress-label to what is counted; never estimate a percentage; otherwise send only a --headline. The app shows progress exactly as sent, never converted to a percentage: a count reads “2 of 5 tables” with a bar, steps read “Step 3 of 8 · “ and the label of the step marked doing, and with no progress there is no bar.

Over HTTP, the same three calls:

Starting is get-or-create on the project, the agent and your external_id: a job that restarts and starts its session again gets the same one back.

Messages in a session

A message with session set belongs to it (kabu sets it from KABU_SESSION). While an ask of the session is pending, the session’s status is waiting.

Ending a session cancels its open asks, and a session that has ended takes no new messages: sending to it is 409 session_ended. Start a new one instead.

Statuses