Agent Approval

Demo & usage

More examples

When to use

• Gating any action an agent takes that spends money, emails a customer, or writes to production.
• Giving an operator a chance to correct a nearly-right action instead of denying and re-prompting.
• Collecting an audit trail of who approved what, with what arguments, and under which policy.
• Queuing approvals for agents that run unattended, so nothing silently blocks or silently proceeds.

Async states

• loading
• error
• retry

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `requests`, `loading` and `error`.
• The load-level retry is `retryLoad` here, because `retry` already means a per-item action on this component.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• `(receipt)` is the immutable record of a decision, emitted beside `(decided)`: who (`[decidedBy]` — the component has no idea who is logged in, so it is `null` rather than a guess), when, through which variant, the risk class it was approved under, the policy that routed it, and **the arguments as executed**. Frozen, arguments included: 'immutable' is a property of the object rather than a promise in a doc comment. `decided` is the instruction; this is what happened.
• `inline`, `modal` and `inbox` are three shapes for **one act**, and the receipt is identical apart from `through` — an audit trail whose contents depend on which shape the operator happened to be looking at cannot be reconciled with anything. One function (`svApprovalReceipt`) builds it for every variant, which is what keeps that true.
• `policySource` on a request answers 'why am I being asked?' in the dialog, in every variant. An operator who cannot tell a genuine escalation from a misconfigured threshold learns to approve everything, and the rule’s own name is the only thing that tells them apart.
• The expiry countdown is a **courtesy, never the enforcement point** — it runs on `Date.now()` in the operator’s browser, which a skewed laptop clock, a slept tab or a deliberately-set system time all move. The component says so beside the timer and folds it into the timer’s `aria-label`. A host that treats 'the button went grey' as authorization having lapsed has put its access control in the client, where anybody can win an argument with it.
• Redaction, from the pack-wide policy (`X-2`): argument values matching `provideSvAiPrivacy({ patterns })` are masked on screen — and a masked argument becomes READ-ONLY, because an input showing `[API KEY]` submits `[API KEY]`, so the operator would edit the mask and approve it as the real argument. Where the policy sets `reveal: true`, a Reveal control restores both the value and the input, and hides again. The decision receipt and the risk classifier always see the REAL arguments.
• `variant` chooses the shape: `inline` in a thread, `modal` for the irreversible, `inbox` for a queue, `policy` for a read-only record of an auto-approval.
• `approveLabel` and `denyLabel` carry domain wording — "Issue refund" reads better than "Approve".
• `showChanges` and `showCost` hide sections a given request does not need.
• `allowRemember` turns always-allow off globally; it is withheld automatically above medium risk regardless.
• `riskFor` owns the risk classification. Editing an argument re-runs it, and a class change re-arms the confirmation, emits `riskReclassified`, and lands in `decided.risk` — the class approved under, not the one requested.
• Each argument’s `description` renders as help text under the field, and `policyReason` explains an auto-approval.
• The `RISK_ORDER`, `msRemaining`, `isExpired` and `formatCountdown` helpers are exported for sorting or thresholding a queue yourself.

Best practices

• Do: Read the argument values from the `decided` payload, never from the original request — that is where an operator’s correction lives.
• Do: Set `expiresAt` on anything time-sensitive. A stale approval is how agents take actions nobody wanted any more.
• Do: Mark an argument `editable` when a plausible-but-wrong value is the likely failure. An amount or a recipient usually qualifies; an id usually does not.
• Do: Pass `riskFor` alongside any `editable` argument that can change what the call destroys. Without it the badge, the two-step arm and the always-allow offer all describe the call as *requested*, not the one about to run.
• Do: Fill in `changes` — an operator approving a diff they can see makes better decisions than one approving a function name.
• Don't: Do not use it for a yes/no on an action already decided — that is Confirm Dialog. This exists for actions that are still proposals.
• Don't: Do not raise `risk` to make something look important. It changes behaviour: high and critical arm behind a second press and lose always-allow entirely.
• Don't: Do not persist always-allow without scoping it — the payload names the tool, but the policy layer should bound it by agent, environment and amount.

Accessibility

• The countdown is `role="timer"` with a spoken label, so remaining time is available without watching it tick.
• Arming a high-risk action surfaces a `role="alert"` explaining that it cannot be undone, before the confirm is possible.
• Editable arguments are real `input` elements with `aria-label`, reachable and correctable by keyboard.
• The inbox pending count is `role="status"`, so a queue that grows while the operator is elsewhere is announced.
• Status is never colour-only — approved, denied and expired each carry a distinct glyph and a text label.
• The modal variant inherits sv-modal’s focus trap, Escape handling and scroll lock rather than reimplementing them.