`turn inspect`

Turn agents are long-running, non-deterministic processes. Standard debuggers are not built for them. You cannot set a breakpoint inside a stochastic inference loop running across thousands of suspended actors.

turn inspect is Turn's answer to that problem. It reads the serialized VmState of any suspended or persisted agent and prints a structured, color-coded snapshot of its complete internal state: context window, durable memory, mailbox, supervisor tree, and the confidence score of the last infer call. No instrumentation is required. No code changes needed.

Usage

turn inspect <agent-id> [--store <path>]

Argument	Default	Description
`<agent-id>`	required	The ID passed to `turn run --id`
`--store <path>`	`.turn_store`	Path to the state store directory

The agent must be in a suspended state, either paused by an explicit suspend call or blocked awaiting a tool result. Inspecting a completed agent reads its last checkpoint.

Creating an Inspectable Agent

Any agent that calls suspend writes its full VmState to the store. The state includes the instruction pointer, execution stack, environment, context, memory, and mailbox, so resumption after inspection is exact.

reconciliation_agent.tn

struct Analysis { invoice: Str, status: Str, discrepancy: Str };

context.system("You are an invoice reconciliation agent for Acme Corp.");
context.append("Processing batch 2847, 500 invoices.");

remember("batch_id", "BATCH-2847");
remember("processed_count", 247);
remember("status", "in_progress");

let result = infer Analysis {
  "Reconcile invoice 1001 against PO-9923.";
};

suspend;

turn run reconciliation_agent.tn --id recon_agent
turn inspect recon_agent

Output Reference

turn inspect prints five sections, each mapping to a distinct layer of the agent's state.

[1] The Tripartite Context

Shows the complete three-tier context window in the exact form the VM holds it, which is the same ordering used when constructing LLM prompts.

[1] THE TRIPARTITE CONTEXT
---------------------------------------------------------
[P0: SYSTEM / PRIMACY] (Locked)
  - You are an invoice reconciliation agent for Acme Corp.

[P2: EPISODIC / MIDDLE] (Demoted)
  - (Empty)

[P1: WORKING / RECENCY] (High Attention Zone)
  - Processing batch 2847, 500 invoices.

Tier	Role	Eviction policy
P0	System prompt. Set by `context.system(...)`.	Never evicted.
P1	Working context. Set by `context.append(...)`.	Oldest entries move to P2 when capacity is reached.
P2	Episodic memory. Receives P1 overflow.	Evicted when P2 capacity is reached.

The rendered prompt order is P0 then P2 then P1, placing the most recent working context in the highest recency position.

[2] Durable Memory

All key-value pairs written via remember. This store is isolated per process and survives restarts.

[2] DURABLE MEMORY (remember / recall)
---------------------------------------------------------
  batch_id        => BATCH-2847
  processed_count => 247
  status          => in_progress

[3] Actor Mailbox

All messages currently queued in this process's mailbox, waiting to be consumed by receive or gather.

[3] ACTOR MAILBOX
---------------------------------------------------------
  [0] {type: ExitSignal, pid: <pid 3>, result: "chunk_done"}

An empty mailbox is expected for any agent that suspended after processing all incoming messages.

[4] Cognitive Belief State

The confidence score of the most recent infer call. This is the primary signal for diagnosing why an agent looped, escalated, or took an unexpected branch.

[4] COGNITIVE BELIEF STATE
---------------------------------------------------------
  Last Inference Confidence: 0.94   (green)
  Last Inference Confidence: 0.61   (yellow)
  Last Inference Confidence: 0.31   (red)

Score range	Color	Meaning
0.80 and above	Green	The model was certain. No intervention needed.
0.50 to 0.79	Yellow	Moderate certainty. Review the prompt and input context.
Below 0.50	Red	Low certainty. The model likely triggered a retry or escalation branch.

[5] Supervisor Tree

The process hierarchy rooted at PID 1. Shows all child processes recorded in this VM snapshot.

[5] SUPERVISOR TREE
---------------------------------------------------------
  [PID 1] recon_agent (Status: Suspended)

Debugging with the OODA Loop

turn inspect maps directly to the Observe-Orient-Decide-Act cycle for agentic debugging:

Observe. Run turn inspect <id> to see the exact state at suspension.
Orient. Read the Cognitive Belief State. A low confidence score explains unexpected loops or escalations.
Decide. Revise the system prompt in P0, tighten the input data, or adjust the confidence threshold.
Act. Run turn run again. The VM resumes from the exact checkpoint.

Because Turn serializes the full VmState including the instruction pointer, every resumption is bit-exact. There is no approximation.

NOTE

The .turn_store directory holds one JSON file per agent ID. These files can be version-controlled, copied between machines, or read directly with any JSON tool. turn inspect is a structured wrapper over that raw state.

turn inspect