Entitlement Assistant · Use Cases

This part follows the system at work: six use cases, each a sequence of who asks whom for what, and then, in words, the ones that vary them. Each section’s sequence comes first; its steps, with the code that runs each, follow beneath it.

1. Chat turn — where the model works, and the guard is hardest
2. Explaining access — why can’t this person do that?
3. Grant at once — within every policy: applied on confirmation
4. Grant by approval — beyond 14 days: a supervisor decides
5. Sweep — what time alone changes, every 15 minutes
6. Case lifecycle — the frame around everything else
7. Other use cases — a revocation, an extension, and the rest

• References

1. Chat turn

A chat turn is where the model works, and where the system guards hardest. The browser opens a WebSocket to the case’s agent; every frame it sends is checked before the Agents SDK sees it; the request to the model is rebuilt from the conversation the server stored, never from what the page sent; and the model’s tool calls come back to the agent, which runs each as the representative.

Rebuilding the request is what makes the chat trustworthy. As the Agents SDK ships, a page sends the whole history with each message, and the SDK stores it; a page could write an earlier reply the assistant never gave, or a tool result no tool returned, and the model would take it as said. Here the page sends only its newest text: the history is the one the server stored, turn by turn, and a tool’s result reaches the model only from the tool (Figure 23).

The model reaches the system through nine tools and nothing else. Eight reach data through a use case and only read or prepare; the ninth drafts text and reaches nothing. None confirms, cancels or decides.

2. Explaining access

Explaining access answers “why can’t this person do that?” with the decision point’s own findings. The use case asks twice: whether the representative may read the account at all, and what the decision point would answer for the person and the operation. Only then does it decide what it may disclose (Figure 24).

Disclosure is the subtle part. A refusal is explained only to someone who holds account.read on the account and was stopped by policies alone; anyone else receives a not-found that is byte for byte the answer for an account that does not exist. A level-1 representative asking about an Enterprise account is told which policy stopped them; someone with no right to read accounts learns nothing, not even that it exists.

One finding comes with a remedy: where the account’s plan lacks a feature, the answer names the lowest plan on its ladder that includes it, and any add-on that does. The use case computes it through the product subsystem, not the decision point, and no code suggests a role. Every other refusal comes with its reason alone, so the representative can say why and the model cannot promise a way through that the system would refuse.

Before it can explain anything, the model has to find the account, and it never guesses one. It finds an account by its id, by part of its name, or by a person’s email; when a name matches two accounts — Acme Corp and Acme Labs — the assistant asks which one is meant rather than picking, and the answer it gives is about the account the representative chose.

3. Grant at once

A grant within every policy applies the moment the representative confirms it. The model prepares it as a change request, stored with its diff and its preview whatever the preview says; the card is drawn from what was stored; the click asks the decision point again, and Allow applies it (Figure 25).

The preview is a courtesy, not a decision. What decides is the confirmation, made for the person who clicks and in the request’s own transaction: the decision, the grant, the account’s new version, the request’s status and every audit record commit together or not at all.

The diff is what the representative confirms. It lists what the change would add to or take from the account’s effective entitlements, computed as the grant’s preview from the same building block every read uses, and it is stored with the request; the card shows the stored diff, and applying it checks the diff’s tests still hold, so the change applied is the change the card showed.

4. Grant by approval

A grant beyond 14 days needs a supervisor, and the system waits for one without holding anything open. The confirmation’s decision is Conditional: the approval, its deadline and the outbox’s message to start a workflow are written in one transaction. After the commit, the relay starts an approval workflow whose id is the approval’s; it waits for the decision until the deadline (Figure 26).

The supervisor’s approval is decided like any action: the supervisor must hold approval.decide, may read the account, and must be neither the request’s requester nor its confirmer — the policy no-self-approval. The approval and the outbox’s decision message commit together; after the commit, the relay sends the workflow its event.

The workflow wakes and applies the change as the approval-process identity, which first decides its own right to apply a change request. Then it decides again for the person who confirmed, with the approval granted: if that person may no longer make the change, it is refused. Only then is it applied, the account’s version checked like any other. At the deadline with no decision, the approval and the request expire.

The supervisor decides with what the representative saw. The approvals panel shows each pending request: the change, who asked and their reason as written, and why it needs approval — the policies’ descriptions, not the model’s words. A denial needs a reason from a fixed list, and the case hears it.

The deadline is the workflow’s own timer, set to the time left until the approval’s expires_at, so a workflow started late still ends on time. When it fires, the approval and its request expire — unless a decision arrived in the meantime, in which case the decision is applied instead, so a supervisor who approved in the last second is not overruled by the clock.

5. Sweep

Every 15 minutes a Cron runs the sweep, which settles what time alone changes. It runs as system identities, and its three stages are apart: one failing stops none of the others (Figure 27).

A grant past its end grants nothing from that moment, whether or not the sweep has come by; the sweep records the expiry so the row says what is already true. The other stages are the safety net under the outbox and the workflows: anything a relay missed, the sweep delivers again.

The outbox waits a minute before the sweep delivers a message again, so a relay still at work after a commit is not doubled by the sweep; and because a workflow’s id is its approval’s, a message delivered twice starts or wakes one workflow, never two.

6. Case lifecycle

A case is the frame around everything else. It opens assigned to whoever opened it; its subject and contact are set by the representative’s clicks; its events form the timeline the agent reads as facts; it closes with a reason and a summary (Figure 28).

The model helps at two points and decides at none. It proposes the subject, which the representative sets; it drafts the summary, which the representative reviews. Closing cancels the requests still awaiting confirmation or approval, but an approval already given is applied after the close.

Authenticating the contact is a person’s judgement, recorded. The representative asks the customer’s security questions or checks the account’s details, and records the result; those two methods are the ones accepted. A change the customer asks for needs the contact’s authentication to be current — within 30 minutes — and the contact to hold a role in the account that lets them ask for it.

The case’s events reach the model as facts, not as instructions: they are written into the system’s own instructions with the case’s state line — the subject, the contact, whether the contact is authenticated — and the model is told that events are what happened, never what to do. That lowers the risk; what bounds it is that no tool can confirm, cancel or decide, and every effect needs a person’s click, so a customer’s words that did sway the model could still change nothing.

7. Other use cases

A revocation runs as a grant applied at once does: prepared, confirmed, decided, applied, and the account’s entitlements back to its plan. An extension is prepared the same way, but counts with the grant it extends, so one that passes 14 days in all needs an approval like a long grant.

A denied approval ends the request refused, with the supervisor’s reason told to the case. A supervisor approving a change they requested or confirmed is refused by no-self-approval, and another supervisor must decide. A canceled request, from the card’s other button, changes nothing: the request stays, canceled, beside its record in the audit chain.

Limits that no approval lifts refuse a change outright. A grant adds at most 100 to a quota, counting the grants that overlap it, and lasts at most 90 days, counting the feature’s grants in the last 90 days, so splitting a large request into small ones does not avoid either. Such a card is refused as it stands, with every reason, and confirming it answers the same reasons.

A suspended account refuses every action but reading it, cancelling a request and handling its case: its entitlements read as nothing, the hold shown to those who may read it, and any grant on it is refused at the decision point’s first stage. An expired grant cannot be extended; the assistant says to prepare a new one. A contact whose own role does not allow what they ask for is refused, so a customer cannot obtain through support what their role denies them.

When the day’s allowance is spent, a chat turn is refused before the model is called, and the connection says why; the case, its panel, its cards and the approvals keep working, since none of them needs the model. When a session’s token expires mid-turn, the WebSocket closes, and the next request needs a valid session.

References

• The project’s API: tech-docs/api/api.md.
• Its feature specifications: tech-docs/features/ — explain access, case lifecycle, grants and approvals, usage guards, employee sign-in.