How do I debug a run that went wrong?

You log with plain console.* and read the timeline the runtime already records. There is no tracer to register and no exporter to configure.

Inside a tool or a workflow step, the runtime captures every console.* line and stamps it with the run it belongs to, the trace of the invocation that produced it and the step that was executing. You thread no run id through your own code. Pass the variable data as an object rather than in the message. Only an object field stays filterable later:

console.info('email sent', { to, templateId }); // `to` is filterable
console.info('email sent to ' + to); // it is not

You get the run timeline without setting anything up. Each 'use step' appears with its timing, its result and every retry attempt. Agent turns show the tools the model invoked with their inputs and outputs, and calls through stackbone.ai record latency and token usage. A run parked on an approval reads as interrupted until the decision arrives.

You do not need Studio open to read any of it:

stackbone runs list
stackbone runs get <run-id>
stackbone logs tail --run <run-id> --follow

Drop --follow and the tail prints what already happened, then exits, which is what you want in a script. --since, --until and --limit narrow it further. Once you know what went wrong, stackbone runs retry <run-id> --yes starts a fresh run from the failed one's input, and stackbone runs cancel <run-id> --yes stops one still in flight. Both change state, so both want --yes.

stackbone dev serves the same runs and the same timeline locally, so what you debug on your laptop matches what the deployed box does. When a CLI command itself fails, re-run it with --json and read error.code and error.suggestion.

Read more

• Logging and observability: what the timeline records and how to read it.
• stackbone runs and stackbone logs: every verb and flag.
• When registration fails: for a box that never came up in the first place.