Module trace 

Session traces for the self-feedback loop (ADR-015).

A session is the execution of one skill (or any caller that opts in through the devboy trace CLI). Events land as JSON Lines at <target>/.devboy/sessions/<YYYY-MM-DD>/<skill>/<session_id>/trace.jsonl, and a sibling meta.json in the same per-session directory carries session-level metadata. The <session_id> segment keeps concurrent or repeated invocations of the same skill on the same day isolated from each other (ADR-015 requires self-contained sessions).

The SessionTracer writer is intentionally small — it serialises one event per line with no framing, no network I/O, and no reliance on the host logging stack. The companion [devboy trace] CLI subcommand family in devboy-cli lets shell-based skills write into the same format.

The redaction pass in redact::sanitize strips values that match known credential shapes and values of environment variables named *_TOKEN / *_SECRET / *_KEY / *_PASSWORD / *_PASSPHRASE / AUTHORIZATION / COOKIE before anything is written to disk.

Modules

redact

Redaction of sensitive values before traces hit disk.

Structs

SessionMeta

meta.json — written at session end and optionally touched during long sessions.

SessionTracer

Appends events to a session’s trace.jsonl.

TraceRecord

One line of trace.jsonl.

Enums

Outcome

Session outcome — recorded on End in both the event stream and the per-session meta.json.

Phase

Event phases. Kept small; readers must silently ignore unknown values.

TraceTarget

Where to write session traces.

Functions

append_event

Append one event to an existing session’s trace.jsonl.

create_session

Create the session directory, write the opening start event, and return the session id + session directory. The returned path is the value the user passed through TraceTarget with the <date>/<skill> /<session_id> suffix appended — it is not canonicalised, so a relative TraceTarget::Custom(".traces") produces a relative path and an absolute target produces an absolute path. Callers pass both values back into append_event and finalise_session on subsequent CLI invocations.

finalise_session

Write the final end event and refresh meta.json with the outcome + aggregated counts derived from the existing trace.