Story-993: structured failure envelope
PR #21 · pramaan-io/pramaan-agents · merged 2026-06-02
How it flows
sequenceDiagram
autonumber
participant runtime as Runtime
participant envelope as Envelope Builder
participant store as Store
runtime->>runtime: run dies (model / tool / validation / resume)
runtime->>envelope: mark failure context
envelope->>envelope: classify kind + build envelope
envelope->>runtime: envelope dict
runtime->>store: fail run (envelope)
store->>store: persist + legacy fields
runtime->>runtime: emit failure event payload
failure_envelope.py · +244 — new methods
| Method | in → out | what it does |
|---|
mark_failure_context | (error, failure_stage, failure_kind, failed_component) → BaseException | |
build_failure_envelope | (error, run_id, firm_id, matter_id, failure_stage, failed_component, created_at) → dict[str, Any] | |
failure_event_payload | (error, envelope) → dict[str, Any] | |
What changed, file by file
| new method | signature |
|---|
mark_failure_context | (error, failure_stage, failure_kind, failed_component) → BaseException |
build_failure_envelope | (error, run_id, firm_id, matter_id, failure_stage, failed_component, created_at) → dict[str, Any] |
failure_event_payload | (error, envelope) → dict[str, Any] |
_classify_kind | (error, stage) → str |
_sanitized_summary | (kind, stage) → str |
_recovery_recommendation | (kind, stage) → str |
_user_visible_message | (kind, stage) → str |
_is_retryable | (kind) → bool |
_retry_after_seconds | (kind) → int |
_internal_debug_ref | (raw_error_class, raw_message) → str |
_context_value | (error, name) → str | None |
_valid_kind | (value) → str |
_valid_stage | (value) → str |
_default_component | (stage) → str |
| new method | signature |
|---|
fail_run | (run_id, error, firm_id, failure_envelope) → None |
What doesn't happen anymore
- raw trace leaked to user
- retry storm triggered
- legacy fields overwritten
- silent misclassification
- envelope without firm id
user-visible message is sanitized
debug ref stays private
legacy class + message preserved
firm id stamped on every envelope
unknown stage on unclassified error
safe back-off if retry is ambiguous
Files changed (8)