Step-by-step trace events + debug mode with screenshots - #8
Merged
Merged
Conversation
Adds TraceEvent, a new op-only channel (separate from AuditEvent, which crosses to a driver's central log, and separate from onError, which stays the "why did this fail" channel) emitted via an injectable onStep callback on FillEngine, RegistrationEngine and CaptureEngine. Each engine traces its real steps (navigate, type_username, type_secret, submit, settle, etc.) and screenshots two coarse checkpoints — never the step where a secret is on the page. CaptureEngine is stricter still: it screenshots only before the generated value can exist. 1claw-browser-bridge --debug <dir> (or ONECLAW_BRIDGE_DEBUG) is the reference consumer: one JSONL trace plus numbered PNGs per run, in bin/debug-trace.mjs. This is also the shape a future 1Claw dashboard would consume for run playback. trace.test.ts asserts the property that matters most here: no detail string or screenshot from any of the three engines ever contains the secret, the generated capture value, or a registration extraFields value. 276 tests passing (was 267), typecheck and build clean.
kmjones1979
force-pushed
the
feat/trace-and-debug-mode
branch
from
September 9, 2026 14:09
cf90a28 to
bacb9d1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
TraceEvent(src/trace.ts): a new operator-only step-by-step record, emitted via an injectableonStepcallback onFillEngine,RegistrationEngineandCaptureEngine, and threaded throughstartBridge'sBridgeOptions. Deliberately separate fromAuditEvent(a driver's own coarse compliance record) and fromonError(which stays the "why did this fail" channel) — see the doc comment intrace.tsfor why merging them would have compromised both.navigate,type_username/type_extra_field,wait_for_field,focus,type_secret,submit,settle,closed/committed/error) and screenshots two coarse checkpoints via the already-allowlistedPage.captureScreenshot— never the step where a secret is on the page.type_secretis traced but never pictured, on principle.CaptureEngineis stricter still: it screenshots onlynavigate, before a generated value can exist, and nothing fromread_valueonward.1claw-browser-bridge --debug <dir>/ONECLAW_BRIDGE_DEBUG(bin/debug-trace.mjs) is the reference consumer: one timestamped run directory per invocation, atrace.jsonlline per step, and a numbered PNG for every step that carries a screenshot. This is also the shape a future 1Claw dashboard would consume for run playback — an ordered trace of named steps with checkpoint screenshots is enough to reconstruct a scrubbable timeline without recording full video or risking the recording itself becoming a leak vector.trace.test.ts(new) asserts the property that matters most: across all three engines, nodetailstring and no screenshot ever contains the fill/registration secret, a capture's generated value, or a registration'sextraFieldsvalue — including on the error path.Test plan
pnpm typecheckcleanpnpm typecheck:testscleanpnpm buildcleanpnpm test— 276 passed, 6 skipped, 30 files (was 267/29 before this change; +9 new trace tests, zero regressions)bin/debug-trace.mjsend to end (trace.jsonl + PNG written correctly for a synthetic event stream)🤖 Generated with Claude Code
https://claude.ai/code/session_01WqPU5z6K3maS9J6LrcsEic