110 lines
6.0 KiB
Markdown
110 lines
6.0 KiB
Markdown
# Task Trace Terminal Verification
|
||
|
||
## Scope
|
||
|
||
Replace the decorative daily-processing status module with a diagnostic view
|
||
that exposes the persisted task flow from upload through downstream outbox
|
||
state. After the first structured UI pass, the user explicitly required the
|
||
plainest possible presentation: one black code console with raw log lines.
|
||
|
||
## Implemented Evidence Path
|
||
|
||
- `GET /api/jobs/{job_id}/trace` validates the job identifier and asks the
|
||
repository for a privacy-minimized diagnostic projection.
|
||
- New tasks are submitted once through
|
||
`POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true`.
|
||
The first `run.started` binds the ARR attempt; the same generator is then
|
||
consumed on a background thread until the SuperAgent run terminal event and
|
||
SSE `end`.
|
||
- Raw SSE and assistant text never reach disk. `arr_processing.agent_trace`
|
||
persists only allowlisted run/task/step/end projections in a private,
|
||
append-only local JSONL store keyed by the job-id digest.
|
||
- `arr_web.job_trace` reconstructs ordered events from the processing run,
|
||
attempts, artifact deliveries or direct MCP submissions, Finance daily
|
||
versions and downstream outbox events, then merges the sanitized SuperAgent
|
||
events by timestamp.
|
||
- Equal PostgreSQL transaction timestamps use an explicit business-sequence
|
||
tie-breaker so validation/Finance commit precede attempt/job success and
|
||
downstream queue events.
|
||
- The desktop page renders the response in a single black monospace `<pre>`.
|
||
Each event is one line containing timestamp, level, stage, code, title,
|
||
message and allowlisted details JSON. The controls remain limited to
|
||
historical task selection, four-second active-task polling, manual refresh
|
||
and one-click copying of the complete current `<pre>` plaintext.
|
||
|
||
## Privacy Boundary
|
||
|
||
The SQL and projection expose only diagnostic columns. `message.delta` and
|
||
`message.final` are always dropped. Trace summaries redact credential
|
||
assignments, Bearer values, URLs, absolute paths, emails, long numbers and XML
|
||
fragments before persistence, and the read path validates the field/details
|
||
allowlist again. The response and UI do not contain grants, credentials,
|
||
private object paths, source bytes, raw payload/envelope/receipt JSON or guest
|
||
PII. Outbox rows are described only as queued/published notifications, not as
|
||
proof of monthly-report completion.
|
||
|
||
The SuperAgent endpoint accepts only POST and does not replay historical runs.
|
||
It was also verified to create a different `run_id` when the exact same message
|
||
and idempotency key are sent twice. ARR therefore never POSTs a second stream to
|
||
backfill logs. An uncertain failure before `run.started` is terminalized as
|
||
`PROCESSING_REMOTE_SUBMISSION_AMBIGUOUS` rather than automatically retried.
|
||
|
||
## Runtime Checks
|
||
|
||
An isolated read-only Web instance on `127.0.0.1:8766` used the configured
|
||
`booking_test` database while the standing 8765 process was left untouched.
|
||
|
||
- A current queued/running task rendered upload, attempt and current-state
|
||
events and continued four-second polling.
|
||
- Successful fixture `mvp-v1-fixture-20260727` rendered 11 events in the
|
||
required upload → dispatch → result → validation → Finance → job → outbox
|
||
order.
|
||
- Failed task `arrjob-fdc2c1a0695c41b3b372a52033b2f567` rendered six events
|
||
and the terminal line
|
||
`FAILURE stage=writeback code=PROCESSING_RESULT_MISSING`.
|
||
- Computed UI evidence was `tag=PRE`, black `rgb(8, 11, 16)`, monospace font,
|
||
and zero old filter/timeline/evidence elements.
|
||
- At a 375×812 viewport, document width stayed 375 pixels; long raw lines
|
||
scroll only inside the console. Browser console error/warning count was zero.
|
||
- Live contract probes confirmed `405 Allow: POST` for GET/HEAD/OPTIONS, the
|
||
outer `trace` SSE event, inner `run.started/task.updated/step.updated/`
|
||
`message.delta/message.final/run.completed`, and terminal `end`.
|
||
- A live isolated background-handoff probe returned the run handle and then
|
||
persisted 45 safe events (28 task updates and 14 step updates) through
|
||
completion/end with no capture failure.
|
||
- The controlled local LaunchAgent was restarted after implementation. Port
|
||
8765 reports database/processing/writeback/monthly readiness, serves
|
||
`arr-job-trace-2`, and correctly returns `agent_trace_events=0` for a job that
|
||
predates trace capture.
|
||
- On 2026-07-30, the live 8765 page showed the copy control disabled before a
|
||
trace loaded and enabled for a 228-line terminal containing the final `END`
|
||
line. A real click completed the page Clipboard API promise and displayed the
|
||
existing success toast; browser console warning/error count remained zero.
|
||
The in-app Browser isolates page, automation and macOS clipboard channels, so
|
||
no external pasteback-equality claim is made. Source and regression checks
|
||
verify that the exact `#process-log.textContent` is passed to the Clipboard
|
||
API, with selected-textarea fallback and explicit failure feedback.
|
||
|
||
## Automated Verification
|
||
|
||
- `node --check arr_web/static/app.js`: pass.
|
||
- 38 post-hardening targeted tests: pass.
|
||
- Full repository suite: 275 tests passed with 2 expected artifact-tool skips.
|
||
|
||
## Result
|
||
|
||
The status module now reports the real SuperAgent execution path plus the
|
||
authoritative persisted ARR processing chain in the user-requested plain
|
||
terminal form. It locates failures by stage and stable error code without
|
||
treating Agent trace as proof of Finance commit or widening the privacy surface.
|
||
Jobs submitted before this capture path was enabled retain only their persisted
|
||
ARR facts because historical Agent trace cannot be replayed.
|
||
|
||
The 2026-07-30 v3 run also established an important limitation: trace capture can
|
||
finish normally while the authoritative ARR job remains `running`. Four-second
|
||
refresh continued and the trace ended at `AGENT_TRACE_STREAM_ENDED`, but no MCP
|
||
callback arrived and the production lifecycle had no terminal reconciler. The UI
|
||
was faithfully rendering stale backend state; trace completion alone must not be
|
||
promoted to business success, but it must trigger or feed a separate terminal
|
||
no-submission reconciliation path.
|