Docs navigation
Docs / Diagnostics and Replay

Diagnostics and Replay

Diagnostics and replay help explain what happened during an OpenSquilla turn. Use them when a result was surprising, slow, expensive, interrupted, or hard to reproduce from the chat transcript alone.

Diagnostics

Diagnostics are runtime logging controls exposed through the gateway.

Check status:

opensquilla diagnostics status
opensquilla diagnostics status --json

Enable diagnostics:

opensquilla diagnostics on

Enable raw turn-call capture when a maintainer asks for deeper provider request evidence:

opensquilla diagnostics on --raw

Turn diagnostics off after collecting enough evidence:

opensquilla diagnostics off

When to Use Diagnostics

Use diagnostics for:

  • provider retries, timeouts, or empty responses;
  • SquillaRouter model decisions;
  • prompt-cache or cache-break investigation;
  • compaction lifecycle events;
  • large tool-result compression;
  • channel delivery failures;
  • unusually high cost or latency.

Avoid leaving raw diagnostics on longer than needed. Raw captures may contain private prompts, tool outputs, local paths, or provider-visible content.

Compaction pauses and Gateway exits

Normal operational logs include content-free compaction timings. compaction.summary_response_received marks a raw provider terminal event before usage settlement and stream cleanup. It does not mean the summary passed validation. The summary_response_processing phase spans usage settlement, iterator exhaustion, and cleanup; compaction.llm_call_completed follows them. Follow compaction.phase_started and compaction.phase_finished with the same compaction_id. The step_name distinguishes attachment projection, historical reference extraction, retained history measurement, summary validation, consumer admission, mutation-lock waits, and durable commit work. Finished records include duration_ms, status, and the exception type when work fails, times out, or is cancelled. They contain no summary or history text and remain available in diagnostic bundles without content capture.

Use pid to correlate those steps with Gateway lifecycle records. Desktop records gateway_process_exit_observed as soon as its owned child exits, including the process instance, exit code or signal, uptime, and any stop or termination request. Windows records the exit status in hexadecimal too. gateway_process_stdio_closed may arrive later if another process still holds an output pipe. CLI records gateway.run_started and gateway.run_finished at the server runtime boundary; the latter does not by itself prove OS process exit.

A phase start without a finish identifies the last observed work, but does not prove a crash or its cause. A hard kill cannot write its own final Gateway log; use the Desktop parent record or the external service manager’s exit evidence. Collect a diagnostic bundle before restarting again when possible.

Replay a Recorded Turn

Replay reads a recorded turn from the decision log and prints a human-readable transcript. It is read-only: it does not re-run tools.

opensquilla replay --session <session-key> --turn <turn-id>

Pipeline steps display OK, SKIPPED, or FAIL. Their outcome is retained even when privacy filtering removes exception text. Older logs that no longer contain enough information to distinguish a failure from a skip display UNKNOWN for those steps.

Use replay when:

  • a chat has moved on but you need to inspect an earlier turn;
  • a bug report needs concise reproduction evidence;
  • you want to compare transcript output with diagnostics and cost data.

TUI Replay Benchmarks

Developers can replay deterministic terminal-chat fixtures without a live provider:

uv run python scripts/bench_tui_replay.py --renderer opentui --fixture long-stream --summary-json .artifacts/tui/opentui-long-stream.json
uv run python scripts/bench_tui_replay.py --renderer opentui --fixture dense-history --summary-json .artifacts/tui/opentui-dense-history.json

Benchmark summaries include renderer availability, event counts, text size, tool and router-decision counts, wall time, flush counts, maximum buffered text, coalescing ratio, transcript item counts, visible viewport counts, expanded tool counts, viewport projection time, final text match status, plugin error count, and errors.

Read features/tui-frontend.md for backend status and tui-real-terminal-harness.md for maintainer terminal-level launch evidence.

Pair Replay With Sessions

Find the session first:

opensquilla sessions list
opensquilla sessions show <session-key>

Export the full session if exact context matters:

opensquilla sessions export <session-key> --output session.md

Safe Sharing

Before sharing diagnostics, replay output, or exported sessions publicly, remove:

  • provider keys and bearer tokens;
  • private local paths;
  • private channel identifiers;
  • customer, project, or account names that should not be public;
  • raw provider prompts or tool outputs that include confidential content.

Read next:


Docs index · Product guide · Improve this page · Report a docs issue

Edit this page on GitHub OpenSquilla docs · synced from main