paybondpaybond
Sign in

T12 · Tutorial

Debug with traces

Read authorize → evidence → result after a smoke: :9477 dashboard, CLI table, hosted replay.

~20 minIntroSandboxoperatorfast evalDebug timeline

Outcome: Locate spend_denied vs released settlement on a vertical trace.

Learning view: objectives and extras expanded. Switch for commands only.

Mental model

Trace is the tool boundary (authorize → evidence → settle), not the model’s chain-of-thought.

You will be able to

  • Separate recording events from opening the dashboard process
  • Identify tool, authorize, evidence, and result phases on the timeline
  • Distinguish spend_denied, approval_required, and released on result

Prerequisites

  • · At least one recorded smoke (dev loop, sandbox smoke, or multi-step execute)
  • · Same project directory that wrote .paybond/dev-trace.jsonl

What the timeline answers

Middleware trace shows the tool boundary — authorization, handler execution, evidence, and sandbox settlement. It does not show model chain-of-thought. Use it when something denies, holds for approval, or settles differently than you expected.

Record then open

  1. Step 1 of 2

    Record events

    dev loop / smoke write .paybond/dev-trace.jsonl but do not start the HTTP UI.

    Goal: Produce events first so CI and local loops can stay headless.

    Run this

    paybond dev loop --offline

    Example response

    ✓ authorize → evidence ok
  wrote .paybond/dev-trace.jsonl

    You should see: .paybond/dev-trace.jsonl is non-empty after the loop.

  2. Step 2 of 2

    Start dashboard

    Same project directory; listens on 127.0.0.1:9477.

    Goal: Open the UI only after events exist.

    Run this

    paybond dev trace

    Example response

    Trace UI listening on http://127.0.0.1:9477
Serving .paybond/dev-trace.jsonl

    You should see: http://127.0.0.1:9477 loads without connection refused.

    Note: Until this process runs, the banner URL refuses connections.

Hosted replay without a local server: /demo/agent-trace. Full event model & CLI: Middleware trace.

Happy-path phases

  1. Toolphase: tool

    Tool call resolved

    tool_selected — travel.book_hotel (or commerce.checkout).

  2. Authorizephase: authorize

    Spend ceiling authorized

    Authorized up to $200.00 (20,000 cents). Denies surface as spend_denied; holds as approval_required.

  3. Evidencephase: evidence

    Evidence submitted

    Auto-evidence after successful handler. Predicate evaluates cost_and_completion against the authorized ceiling.

  4. Resultphase: result

    Settlement released

    Captured $187.00; unused $13.00 released. Settlement amount cannot be overridden by the caller.

Verify before you continue

Check these off against your terminal or timeline output — progress stays on this device.

0/3

If something goes wrong

  • If you see

    No events after opening the dashboard first

    Do this

    Record with dev loop / smoke first (or refresh after new events); dashboard tails the jsonl file.

  • If you see

    Looking for LLM reasoning in the timeline

    Do this

    Only tool-boundary phases appear — use agent logs for chain-of-thought.

Self-check

Answer without scrolling up — then reveal the model answer to compare.

If authorize is amber spend_denied, which files or policy fields do you inspect first?

Next steps

Pick a branch — not every path needs every tutorial.

Related docs & recipes

Recipes are copy-paste production smokes — not repeated inside this tutorial.