RunTaskResult

Type

The output of a `runTask` call: typed output, plus turns, usage, a per-call log, and a trace id.

What runTask resolves to. In schema mode output is validated and typed from your outputSchema, so use it directly; in example mode, check parsedSuccessfully first. toolCalls is the execution log to reach for when a run surprises you (an empty list means the model never called a tool, usually a prompt problem), usage carries the cost in nanodollars, and traceId points at the full transcript the platform kept. Even when the call succeeds, hitMaxTurns or a stopReason of max_tokens means the answer may be thin or cut off, and a truncated tool call means the model saw only part of that result, so record these with the run.

RunTaskResult.ts

interface RunTaskResult<T> {
  output: T
  outputRaw: string
  parsedSuccessfully: boolean
  turns: number
  hitMaxTurns: boolean
  stopReason: string | null
  usage: { inputTokens; outputTokens; totalBillingCost }
  toolCalls: { name; success; durationMs; truncated? }[]
  traceId: string
}

Fields

output

The structured output. With outputSchema, validated and typed from the schema.

outputRaw

string

The raw model text before JSON parse. Useful when output is garbage.

parsedSuccessfully

boolean

Whether output was valid JSON. Always true in schema mode (a failure throws instead); check it in example mode.

turns

number

How many loop iterations the run used.

hitMaxTurns

boolean

The run used every turn in maxTurns, then answered with its tools taken away. The output is what it could say from what it had gathered.

stopReason

string | null

Why the final answer stopped: end_turn, max_tokens when cut at the output limit, or repetition when the platform cut an answer that began repeating. Null when that model call failed.

usage

{ inputTokens, outputTokens, totalBillingCost }

Token counts and total cost in nanodollars.

toolCalls

{ name, success, durationMs, truncated? }[]

A summary of every tool call, in order. The first thing to check when a run misbehaves; empty means the model used no tools. truncated marks a result over maxToolOutputChars, of which the model saw only the beginning.

traceId

string

Stable id for the run's model transcript, recorded server-side. Inside a jewel, attach it to the return to keep the transcript with the pair.

Use the result

const r = await mindstudio.runTask({ /* ...outputSchema... */ });
await Records.update(id, r.output);   // typed, validated
if (!r.toolCalls.length) console.warn('agent called no tools');
if (r.hitMaxTurns || r.stopReason === 'max_tokens') console.warn('answer may be thin or cut off');