FlowRelay
Reference
Action previews
Preview, confirmation, idempotency, metering, audit, and refusal behavior for approved actions.
On this page
Intent lifecycle #
For preview_or_execute operations, the lifecycle is preview -> confirm -> execute. Execute without the required matching preview and confirmation is refused. This lifecycle does not apply to read_only, handoff_only, or direct create_resource operations.
| Stage | What happens |
|---|---|
| Preview | A preview explains the target, current configuration, possible side effects, the authority required, and the idempotency key that will carry into execute. |
| Confirm | A human or authorized agent confirms the exact action inside the grant and product boundary. |
| Execute | FlowRelay performs the action, records audit context, and returns the result or refusal. |
Actions that need previews #
Use action previews for replay, diagnostics sharing, endpoint edits, secret rotation, endpoint deletion, and support request preview/submit. Each records audit context on execute or refusal. Endpoint creation and expansion or feature requests are direct create_resource operations and do not use this lifecycle; endpoint-test intent is handoff_only and returns sender-owned test instructions rather than sending traffic.
Direct creation and support submission #
Endpoint creation executes when the scoped request is accepted and returns its new secret once. Expansion and feature requests record non-binding request resources directly with expansion:request scope. Support request preview and submit use explicit request states, consent, redaction, and idempotency, but the API does not claim that submit is coupled to a persisted matching-preview record.
Idempotency #
Carry the same idempotency key from preview to execute. Generate a fresh preview, and a new key, if the target, payload, endpoint, event, or actor changes. Reusing a key after any of these changes is refused.
Metering #
FlowRelay counts action previews separately from executed actions. Repeated preview loops can hit short-window rate limits or sustained fair-use review even when no action is executed, so check plan usage before broad reads, polling, or repeated previews.
Audit and refusals #
Audit preserves who previewed, who confirmed, what was executed, and which grant allowed it. Refusals explain the missing scope, unsafe state, expired retention, usage limit, or product boundary.