Skip to main content

​
Resolution Flow

This page traces a proposed action from the moment an agent calls inquire to the moment the agent receives a signed verdict. It covers what the user experiences and the states a Q card moves through.

​
The user journey

1

A BotShield Q push arrives

When the agent proposes an action, BotShield sends the user a BotShield Q push notification to the BotShield app. The notification is intentionally thin: it carries the request_id, the agent’s display name, and the action summary. It does not carry the card body.
2

The user opens the Q card

In the app, the action appears as a Q card describing what the agent wants to do — the summary title, an optional detail row (e.g. TOTAL · $48.00), the requesting agent, the Trusted Account the action would use, and the time remaining before it expires. The header reads “BotShield Q” whenever cards are waiting.
3

The user stages a decision

The user taps Confirm or Deny. A user can stage decisions across several pending cards and resolve them together.
4

Biometric ceremony

The user completes a single Face ID / Touch ID ceremony (hardware-backed, via the Secure Enclave). One ceremony can resolve N staged cards at once.
5

Proof of Resolution issued

On a successful ceremony, BotShield signs one Proof of Resolution per card and delivers it back to each card’s agent. The cards move to their terminal state.
One ceremony, N proofs. When a user confirms several cards in one Face ID touch, every resulting Proof of Resolution shares the same ceremony_id — but each is independently verifiable by its own agent, and no agent sees another agent’s proof.

​
Q card states

A Q card has a single, terminal lifecycle. Once it leaves queued, it never returns.
Absence is the signal. cancelled and expired produce no Proof of Resolution. A timed-out or withdrawn action is simply not authorized — there is no negative token to deliver. Only an explicit denied carries a signed verdict.

​
How the agent learns the outcome

The agent receives the result two ways — use whichever fits: A common hybrid: the agent polls for a short window for a snappy in-conversation result, and your backend relies on the webhook for the durable record in case the agent’s task ends before the user responds.

​
Cancellation and expiry

  • Cancel is agent-initiated. Call agentlink/cancel while the card is still queued to withdraw it. It is a no-op (idempotent) if the card has already resolved.
  • Expiry is automatic. A periodic internal sweep marks every queued card past its ttl_at as expired and fires q.resolution.expired. The default TTL is 10 minutes; agents may request [60, 86400] seconds.

​
Failed biometric

If the biometric ceremony fails (wrong face, cancelled prompt), no Proof of Resolution is produced and the staged cards remain queued — the user can simply retry. A failed ceremony is architecturally identical to a timeout: an absence of attestation, never a denied.

​
Next steps

Proof of Resolution

The signed artifact: claims, JWKS verification, and webhook payloads.

Q API Reference

Every operation with request and response shapes.