Executions

One execution is one agent loop: the model runs, calls capabilities, reads the results, and runs again until it has an answer. However many steps that takes, it bills as one.

What an execution is

You send messages. Cheela returns a transcript, token counts, a finish reason, and a duration. Between those two points it may have called the model a dozen times and your endpoint twenty more.

interface ExecutionResult {
  executionId: string;
  status: "completed" | "failed";
  messages: readonly Message[];
  finishReason: "stop" | "tool_calls" | "length" | "error";
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  durationMs: number;
  error?: string;
}

The loop

1. Call the model with the transcript so far and your capabilities as tools.
2. Append the model’s message to the transcript, and its shape to the trace.
3. If it contains no tool calls, stop — that message is the answer.
4. Otherwise dispatch each tool call to your endpoint, in parallel up to a cap, and append the results.
5. Go back to step 1.

Token usage accumulates across every step rather than being overwritten, because the execution is billed for all of them.

Messages and parts

A message has a role and a list of parts. Parts are how tool calls travel in the same structure as text.

type MessageRole = "system" | "user" | "assistant" | "tool";

type MessagePart =
  | { type: "text"; content: string }
  | { type: "tool_call"; id: string; name: string; input: unknown }
  | { type: "tool_result"; toolCallId: string; name: string; output: unknown };

interface Message {
  role: MessageRole;
  parts: readonly MessagePart[];
}

A minimal request is one user message with one text part:

{
  "messages": [
    { "role": "user", "parts": [{ "type": "text", "content": "Where is order 8812?" }] }
  ]
}

The returned transcript includes everything that happened in between, so reading the tool_call and tool_result parts tells you exactly which capabilities ran and what they returned.

How a loop ends

Failure is not an error

Two things fail independently, and Cheela reports them differently.

• A capability that throws becomes a tool_result carrying an error, and the loop continues. One bad call does not abort the whole run — the model gets to see what went wrong and try something else.
• An execution that fails still returns HTTP 200, with status: "failed" and an error string in the body.

Streaming

Send Accept: text/event-stream and the same execution arrives as server-sent events. Without the header, the response is unchanged — this is content-negotiated, so nothing breaks by adding it.

curl -N https://api.cheelalabs.com/v1/runtime/execute \
  -H "Authorization: Bearer $CHEELA_PUBLIC_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [...] }'

Streaming does not make an execution faster. Nearly all of a request’s wall time is the provider generating tokens, and no amount of engineering on this side moves that. What it changes is that the user stops waiting in silence for the whole thing.

The stream always terminates with a done event carrying the same ExecutionResult the JSON path returns — including when something fails, because the status line has already been sent by then.

What gets counted

One execution is one unit, no matter how many steps the model takes to complete it. Capability calls are counted and reported, but they are not a limit.

Quota is a token bucket rather than a per-hour counter, so a quiet hour pays for a busy one. Bucket capacity is your hourly rate multiplied by your rollover window:

Usage responses carry periodStart and periodEnd, so a dashboard can say “resets in 23m” rather than leaving people to guess.

Broker calls

Anonymous calls through the public broker spend the owner’s quota, and draw on a smaller sub-allowance as well as the main one. Without that, traffic against a public manifest could starve the owner’s own widget — which is a remote denial of service against anyone who publishes one.

Traces

Every execution is recorded: every capability call, token counts, duration, any error, and the shape of the conversation. List them with GET /v1/executions, fetch one with GET /v1/executions/:executionId.

Your handler receives the same executionId Cheela recorded, so logging it joins your own logs to the trace:

async handler(context, input) {
  logger.info({ executionId: context.executionId }, "order lookup");
  // ...
}