1.5 KiB
1.5 KiB
Probe Stream Semantics Before Designing Trace Capture
Trigger
The user pointed to SuperAgent's
/messages/stream?include_trace=true capability after the first task-log
implementation reconstructed only ARR database facts. The URL alone did not
establish whether it could replay an existing run or only create a new one.
Evidence
OPTIONS,HEADandGETreturned405 Allow: POST.- A no-business-data probe showed the first SSE event was
run.started, followed by task/step updates and a terminal run event/end marker. - Repeating the exact same message and idempotency key created a different
run_id; the endpoint did not replay or deduplicate the prior run.
Lesson
Do not infer read/replay semantics from an observability query parameter. Before wiring trace capture, verify the HTTP method, event order, connection lifetime and duplicate-submission behavior with an isolated harmless request. If trace is emitted only while creating the run, return the handle from the first start event and keep consuming that same connection; never POST again merely to recover diagnostics.
Reusable Check
- Probe non-mutating methods first and inspect
Allow/Content-Type. - Use a separate no-PII session for the smallest authorized POST probe.
- Record only schema/event names until the privacy boundary is known.
- Test identical idempotency keys explicitly; do not assume endpoint parity.
- Treat an uncertain post-send failure as ambiguous when the server cannot prove deduplication.