Jidoka.Debug (Jidoka v0.9.0)

Data-first request debug and replay diagnostics.

Jidoka.Debug assembles useful debug views from values Jidoka already produces: turn results, sessions, snapshots, journals, events, and replay projections. It never calls LLMs, tools, memory stores, or runtime capabilities.

Use this module after a turn when you need one value that explains the request: prompt messages, selected operations, operation results, usage, timeline, journal, pending reviews, and replay diagnostics.

{:ok, result} = Jidoka.turn(MyApp.Agent, "Check order A1001")
{:ok, summary} = Jidoka.Debug.request(result)

summary.prompt.messages
summary.operation_results
summary.usage
summary.replay_diagnostics.status

Request summaries accept:

Jidoka.Turn.Result for a completed turn;
Jidoka.Session.Data for the latest request, or a specific request_id:;
Jidoka.Snapshot for hibernated work;
Jidoka.Session.Replay for stored replay projections;
common return tuples such as {:ok, result} and {:hibernate, snapshot}.

Jidoka.Debug intentionally stores context keys, not full context values. Keep secrets and large application payloads in your application data, not in debug summaries.

Replay diagnostics use four statuses:

:complete - all recorded effect intents have results;
:waiting - human review is pending;
:failed - an effect result or timeline event failed;
:incomplete - at least one effect intent has no recorded result.

Summary

Functions

diagnose(target)

Diagnoses replayable runtime data without executing effects.

latest(session, opts \\ [])

Returns the latest request summary for a session.

request(target, opts \\ [])

Builds a request-level debug summary from a result, session, snapshot, or replay.

Functions

diagnose(target)

@spec diagnose(term()) :: {:ok, Jidoka.Debug.ReplayDiagnostics.t()} | {:error, term()}

Diagnoses replayable runtime data without executing effects.

Diagnostics flag missing effect results, failed effect results, unsafe effects, pending reviews, and failed timeline events.

Use this when you have a session, snapshot, replay, result, or journal and need to know whether the recorded data is complete enough to inspect or replay safely.

latest(session, opts \\ [])

@spec latest(
  Jidoka.Session.Data.t(),
  keyword()
) :: {:ok, Jidoka.Debug.RequestSummary.t()} | {:error, term()}

Returns the latest request summary for a session.

This is a convenience wrapper around request/2. Pass request_id: to select a specific request in the session history.

request(target, opts \\ [])

@spec request(
  term(),
  keyword()
) :: {:ok, Jidoka.Debug.RequestSummary.t()} | {:error, term()}

Builds a request-level debug summary from a result, session, snapshot, or replay.

The summary combines prompt debug metadata, operation results, usage, timeline, journal, pending reviews, and replay diagnostics. It is data-only and never calls runtime capabilities.

Options:

:session - attach a session id when summarizing a snapshot or result;
:request_id - when the target is a session, select a specific stored request or snapshot. Unknown ids return {:error, {:request_debug_not_found, session_id, request_id}}.