36 lines
1.5 KiB
Markdown
36 lines
1.5 KiB
Markdown
# 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`, `HEAD` and `GET` returned `405 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
|
|
|
|
1. Probe non-mutating methods first and inspect `Allow`/Content-Type.
|
|
2. Use a separate no-PII session for the smallest authorized POST probe.
|
|
3. Record only schema/event names until the privacy boundary is known.
|
|
4. Test identical idempotency keys explicitly; do not assume endpoint parity.
|
|
5. Treat an uncertain post-send failure as ambiguous when the server cannot
|
|
prove deduplication.
|
|
|