| 1 | package tool |
| 2 | |
| 3 | import ( |
| 4 | "context" |
| 5 | "encoding/json" |
| 6 | ) |
| 7 | |
| 8 | // EffectInspection is evidence from the tool's authoritative sink. Absent is |
| 9 | // retry-safe only when Fenced proves an older attempt can no longer commit. |
| 10 | type EffectInspection struct { |
| 11 | State string // present | absent | unknown |
| 12 | Fenced bool |
| 13 | Summary string |
| 14 | } |
| 15 | |
| 16 | // EffectVerifier is optional. Unsupported tools remain unknown; generic shell |
| 17 | // commands and arbitrary MCP tools are never assumed idempotent. |
| 18 | type EffectVerifier interface { |
| 19 | RecoveryScope() string // stable sink/account/resource identity, independent of a retry |
| 20 | InspectEffect(context.Context, string, json.RawMessage) (EffectInspection, error) |
| 21 | } |
| 22 | |
| 23 | type recoveryKey struct{} |
| 24 | |
| 25 | // RecoveryIdempotencyKey is stable across explicit retries of one action. |
| 26 | func RecoveryIdempotencyKey(ctx context.Context) string { |
| 27 | v, _ := ctx.Value(recoveryKey{}).(string) |
| 28 | return v |
| 29 | } |
| 30 | func WithRecoveryIdempotencyKey(ctx context.Context, key string) context.Context { |
| 31 | return context.WithValue(ctx, recoveryKey{}, key) |
| 32 | } |
| 33 |