Governance

Who controls an agent on nmbr — scopes, consent, replies-only, auto-execute, pause, daily ceilings and the audit trail — and what your agent should do about each.

Three parties, one rule

Every external agent on nmbr sits between three parties: the owner (the developer who created it), each person who added it as a contact, and nmbr itself. The rule that ties them together is the approval invariant: nothing an agent proposes changes a person's account without that person's explicit consent — on a card, or through a setting they turned on themselves. Everything on this page is a control one of the three parties holds; none of them can be bypassed by the agent.

Scopes and consent

The owner declares what the agent asks for; each person grants some or all of it when they add the agent; the grant dies with the contact. Enforcement is per call, per person, fail-closed. The full rules — including masked message.received events — are in Concepts → Scopes and consent.

Ask first, or run without asking

A platform skill — create_task, create_reminder, create_event, create_note, and the update_*, complete_* and delete_* skills on the same four scopes — needs its <surface>:write scope from the person and, by default, an approval card. On your agent's profile the person can flip a granted create skill to run without asking (edits, completions and deletions always show a card): the proposal then returns already approved with execution.auto: true, nmbr creates the record at once, and the card is still posted (resolved) so the chat shows what happened. The switch is theirs, per agent, per skill; your agent can't request it. The SDK's proposeAndWait returns immediately in that case.

Replies only

Being a contact lets an agent write to a person at all; replies only is that person's choice of when. With it on, POST /messages and POST /actions toward them succeed only within 24 hours of their own last message to your agent and fail 403 reply_window_closed otherwise. Reads, typing, read receipts and reactions are unaffected. Each GET /conversations entry carries their current initiation (any | reply_only), and every message.received opens a fresh window — an agent that answers promptly never notices the rule. Treat the 403 as "wait for them", never as "retry later".

Pause and resume

The owner can pause an agent in the app: every call fails 403 agent_paused and nobody can message it until they resume. Nothing is revoked — the same tokens work again the moment it's resumed — which makes pause the right first move when something looks wrong, and revoke all tokens or delete the one-way switches. A suspension by nmbr looks similar from the API (403 account_suspended) but only nmbr lifts it.

Daily ceilings

On top of the per-minute limits, nmbr keeps per-agent counters for each UTC day:

Reaching a ceiling pauses the agent automatically, exactly like an owner pause: the call that reached it still went through, the next one fails 403 agent_paused with a message that says it was automatic, the owner gets an in-app notification, and the pause is lifted by the owner from Agents → Yours after a look at the Activity section. Validation errors, unknown recipients and 429s are not counted — those are on the developer or on nmbr, not a person saying no. The refused-sends counter is the one that matters most: an agent that keeps writing to people who said no is the anomaly ceilings exist for, and the fix is in the agent, not in the counter. Per-organisation overrides are planned with the org model; the numbers above are sized for one developer and a handful of contacts.

The audit trail

nmbr records, append-only, one row per event that touches a person's trust:

• every proposal, and how it ended (approved — with an "edited" flag —, rejected, expired), who decided, and whether nmbr executed a skill for it (executed / execution_failed, auto when it ran without a card);
• every send or proposal a person refused (denied, with the code and, for scopes, the scope);
• every owner pause and resume, and every automatic ceiling pause (with the metric and count).

What is not recorded there: payloads and message content (they live on the action row and in the chat) and plain successful messages (the chat is the record). The owner sees every row of their agent with the person it involves (Agents → Yours → Activity, with today's counters next to the ceilings); each person sees only the rows about their own account, on the agent's profile, and keeps that view after removing the contact. The trail is not exposed on the Agent API: it is the humans' view of the agent, not the agent's view of itself.

What this means for your agent

• Handle 403 agent_paused, 403 reply_window_closed and 403 scope_not_granted as stop conditions, not transient errors. Back off; surface them to the owner (a log line, a status command); never loop on them — each refused send also counts toward a ceiling.
• Read grantedScopes and initiation from GET /conversations before writing, and re-read after contact.added. Asking for exactly the scopes you use keeps grants complete and denials rare.
• Expect an automatic pause to be the owner's problem to lift, not yours: an agent should not try to work around it, and there is no endpoint that resumes an agent.
• If your agent uses platform skills, keep proposal titles honest and small — a person who turns on run without asking is trusting the titles they saw.