Skip to content
Hexel StudioDocs

Tasks and runs

Create a task, follow its events live, steer it, answer its questions, pause, resume, retry or cancel it, and understand what the harness keeps.

On this page

A task gives an agent a goal. It keeps going until it is done: it survives restarts, waits for people when it needs them and stops at its budget. Each attempt at a task, and each sub-agent it starts, is a run.

Create a task

Bash
hexel harness task create "Audit the api repo" --agent auditor@prod \
  --input repo=acme/api --budget-usd 5 --follow
FieldDescription
goalWhat the agent should do. Up to 64 KiB.
agentname (its prod channel), name@channel or name@v<n>.
inputsOptional JSON object, up to 256 KiB. The agent receives it with the goal.
budgetOptional limits: see Budgets and estimates.
sandbox_templateOptional. The sandbox template for the task's computer.
after, inputs_from, checkinOptional. See Task chains.

A task belongs to the person who created it, in the workspace and environment of the request. Members see and act on their own tasks; Admins and Owners (harness:task:admin) on everyone's.

States

StateMeaning
queuedAdmitted and waiting for the runtime to start it.
runningThe agent is working.
waitingThe agent waits; waiting_reason says on what (below).
pausedPaused by a person. A paused task holds no capacity.
succeededDone. Its outputs hold the result.
failedEnded without success; end_reason says why.
budget_exhaustedStopped at its budget. Resume it with a new budget.
cancelledCancelled by a person.
waiting_reasonThe task waits for
questionAn answer to the agent's question.
approvalA Titan approval of one of its actions (Approvals and autonomy).
dependencyThe tasks it starts after (Task chains).
parkedAn answer, for more than an hour (below).
fork_workerA runtime that can start a forked run.

Parking. A run that has waited an hour for an answer, with nothing in flight, is parked: it holds no runtime capacity and shows waiting_reason: parked. An answer or a steer wakes it, and it continues where it was. With nothing arriving, it is looked at again after 6 hours and parked again if it still waits. A parked task can be paused or cancelled.

Follow a task

A task's events stream as Server-Sent Events: first the stored events, then live ones until the task ends, then an end event.

Bash
hexel harness tail -f tsk_123                          # follow until it ends
hexel harness tail tsk_123 --only message,tool         # only some event types
hexel harness tail tsk_123 --after 120                 # pick up after event 120
Bash
curl -N https://api.hexelstudio.com/v1/harness/tasks/tsk_123/events \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" -H "X-Environment-Id: $ENVIRONMENT_ID"
  • Each SSE event's event: is its type and data: the event envelope. Events lists every type.
  • To resume after a dropped connection, send Last-Event-ID or ?after=<event id>. The SDKs do this for you.
  • ?types= filters by type, ?run= narrows a task's stream to one run, and ?follow=false returns the history and stops.
  • GET /harness/runs/{id}/events streams one run.

Steer a task and answer it

Bash
hexel harness steer tsk_123 "Skip the vendored code"          # read at the agent's next step
hexel harness steer tsk_123 "Stop and summarise now" --now    # interrupts what it is doing
hexel harness answer call_456 "api and web"                      # answer a question
hexel harness answer call_456 --decline                          # decline to answer

The agent asks with ask_user; the question arrives as a question.asked event and in GET /harness/tasks/{id}. Through the API, steer with POST /harness/tasks/{id}/messages {"text": "...", "mode": "queue" | "now"} and answer with POST /harness/questions/{id}/answer {"answer": "..."} (null declines). A finished task takes no steer or answer.

Control a task

CommandAPIWhat it does
hexel harness task pausePOST /tasks/{id}/pauseThe agent stops after its current step.
hexel harness task resumePOST /tasks/{id}/resumeContinue a paused task, or one out of budget with a new budget (--budget-usd).
hexel harness task retryPOST /tasks/{id}/retryStart a failed, cancelled or out-of-budget task again.
hexel harness task cancelPOST /tasks/{id}/cancelCancel it.
hexel harness task deleteDELETE /tasks/{id}Delete it and everything under it; its running agent is stopped. See Data retention.

Resume and retry are admitted like a new task: they are checked against your plan, balance and limits.

Runs

Bash
hexel harness task runs tsk_123     # attempts and sub-agents
hexel harness run get run_789       # one run, with what Titan knows of its session

A retry starts a new attempt, a new root run. A sub-agent the agent starts is a child run with its own events. GET /harness/runs/{id} includes the run's Titan governance state: its Titan session and lifecycle.

Content and history

The harness's control plane stores metadata: ids, states, costs, sizes and keyed digests (hmac-sha256:...). The content of an event (message text, tool arguments and results, questions and answers) stays in the runtime that ran the task.

  • Live. An open stream receives the content as it happens, in event.content chunks that carry no id and are not stored. The SDKs and the CLI join them for you. At most 1 MiB is relayed per event.
  • History. Events read back later (?after=, Last-Event-ID, ?follow=false) carry metadata only: each content field is replaced by its digest and size.
  • Task fields. A task's outputs show {digest, size}. Once a task has succeeded, its goal and inputs are emptied and their digests stay; a failed or cancelled task keeps them so that it can be retried.
  • Commands. Steers, answers and decision reasons lose their content once applied or once the task ends.

Follow a task while it runs if you need its content, or have the agent export what matters as an artifact.